本地包版本冲突源于Composer将path仓库的composer.json视为正式依赖节点，强制解析其require字段，需手动对齐版本边界；应删version字段、用replace或conflict显式干预依赖图。
直接装本地包时出现版本冲突，本质是 Composer 把本地路径当作了“真实包源”，但没自动处理其 composer.json 里声明的依赖约束——你得手动对齐它和项目其他依赖的版本边界。
为什么 composer require path:./packages/my-package 会触发冲突
Composer 对 path 类型仓库的解析逻辑很直接：它会读取本地包根目录下的 composer.json，把里面的 require 字段当作硬性依赖加载进来，不加缓冲、不降级兼容性判断。如果你的本地包写了 "monolog/monolog": "^3.0"，而项目主 composer.json 锁的是 ^2.9，Composer 就会立刻报 Root composer.json requires monolog/monolog ^2.9, found monolog/monolog[3.0.0]。
- 本地包的
composer.json不是“建议”，而是参与全局依赖图计算的正式节点 -
path仓库默认开启symlink，但 symlink 不绕过版本校验 - 即使本地包本身没发布过任何 tag，它的
version字段（或通过branch-alias）仍会被用于稳定性判断
解决前先确认本地包的 version 声明是否合理
很多冲突其实源于本地包 composer.json 里写了不必要或错误的 version 或 branch-alias。比如：
- 写了
"version": "dev-main"，但项目要求stable稳定性，就会被跳过或报错 - 写了
"branch-alias": {"dev-main": "3.0.x-dev"}，结果 Composer 把它当成3.0大版本参与解析，抬高了整个依赖树的下限 - 根本没写
version，Composer 会 fallback 到1.0.0+no-version-set，这个值在某些旧版 Composer 中可能被误判为不稳定
建议删掉 version 字段，靠 require 和 conflict 显式表达兼容性，而不是靠伪造版本号“骗过”解析器。
用 replace 或 conflict 主动干预依赖图
当本地包和已有依赖在同一个库上存在不可调和的版本差（比如一个要 symfony/event-dispatcher ^6.4，另一个要 ^5.4），光改 require 不够，得用 Composer 的元指令强行收口：
- 在项目根
composer.json的replace字段中写："symfony/event-dispatcher": "self.version"，表示“我自己的版本就是权威，其他所有来源都算被我替代” - 如果本地包明确不兼容某个范围，用
conflict更安全："guzzlehttp/guzzle": "，这样 Composer 在解析时会直接排除掉冲突组合 -
replace不能跨 major 版本“假替真”，比如用^6.0去 replace^5.0，运行时大概率出错——它只解决安装阶段的“能装上”，不解决 API 兼容性
临时绕过但不掩盖问题的操作方式
开发调试阶段想快速验证功能，可以临时压制冲突，但务必记在 TODO 里后续修复：
- 加
--ignore-platform-reqs只跳过 PHP/扩展检查，对包版本冲突无效 - 加
--no-update后手动编辑composer.lock强行写入本地包路径，风险极高，容易导致下次composer install覆盖掉 - 最可控的是用
composer require vendor/name:dev-main --repository-url=./packages/my-package，把本地包当作独立仓库源引入，并在该仓库配置中指定"type": "path"和"options": {"symlink": false}，避免符号链接干扰版本判定
真正麻烦的从来不是“怎么让它装上”，而是“装上之后哪段代码会在 runtime 突然挂掉”——本地包的 require 必须和项目主干保持语义一致，否则 replace 只是给炸弹贴胶带。
