Composer版本冲突本质是多个模块对同一依赖提出无交集的语义化版本约束，需在私有模块目录下运行composer why-not定位真实阻塞源，优先调整私有包require字段的宽松约束，警惕require-dev隐式拉取及conflict字段全局拦截。
模块化开发中出现 Composer 版本冲突，不是“装不上某个包”，而是多个模块对同一依赖提出了无法共存的语义化版本约束——Composer 已穷举所有组合，没交集就直接放弃。
composer why-not 必须在私有模块根目录下运行
很多人在主项目里执行 composer why-not vendor/private-sdk:^2.3，结果输出一堆无关路径。问题在于：私有 SDK 的约束是否生效，取决于它当前是通过 path 源加载还是 Packagist 镜像安装。如果你本地用 repositories 指向 ./packages/private-sdk，那 why-not 就必须进那个目录里跑，否则查不到它 composer.json 里真实的 require 范围。
常见误判现象：
- 主项目报
Conclusion: don't install monolog/monolog:^3.0，但在主项目目录跑composer why-not却显示 “no matching packages” -
composer show --tree显示已装monolog/monolog 2.9.3，但实际阻塞源是私有模块自己锁死了"monolog/monolog": "2.9.3"
正确操作顺序：
- cd 进私有模块目录（如
packages/private-sdk） - 执行
composer why-not monolog/monolog:^3.0 - 若输出
your-private-sdk dev-main requires monolog/monolog 2.9.3，说明约束源头就在你自己的composer.json里
私有模块的 require 字段禁用精确版本
私有模块不是“关起门来随便写约束”的地方。一旦被多个项目复用，"guzzlehttp/guzzle": "7.4.5" 这类精确版本会立刻变成下游项目的硬性枷锁：只要另一个模块要 ^7.5 或 ^8.0，Composer 就无解。
可行做法：
- 改用语义化范围：
"guzzlehttp/guzzle": "^7.2 || ^8.0"（前提是你的代码真能兼容两套 API） - 更稳妥的是只写
"guzzlehttp/guzzle": "^7.2"，再靠 CI + 多版本测试覆盖验证 - 绝对不要写
"monolog/monolog": "2.8.0"或"symfony/console": "6.4.0"这类钉死版本
注意：conflict 字段不能替代宽松 require——它只做拦截，不参与版本协商；而 replace 是替身机制，不是兼容方案。
require-dev 是模块化冲突最高发区域
主项目用 laravel/framework: ^10.0，却让私有模块带入 orchestra/testbench: ^7.0，后者内部硬绑 Laravel 9，冲突当场触发。这类问题在模块化开发中高频，因为每个模块都可能自带一套 require-dev，且 Composer 默认把它们全纳入依赖图解析。
典型雷区：
-
phpunit/phpunit拉入不兼容的symfony/console或sebastian/exporter - 旧版
mockery/mockery锁死php: >=7.3，与主项目 PHP 8.1 环境冲突 - CI 脚本里未清理
require-dev就跑composer install --no-dev，导致本地缓存污染
规避建议：
- 模块发布前，用
composer install --no-dev && composer dump-autoload --classmap-authoritative验证生产环境行为 - 模块的
composer.json中，require-dev只保留真正必需的测试工具，删掉历史残留（如过时的behat/behat） - 团队规范：模块 PR 必须附带
composer why <conflicted-package></conflicted-package>输出，证明无隐式拉取
模块间语义化交集必须手动验证，不能靠 Composer 推导
Composer 不会帮你找“哪个版本同时被 A 的 ^2.0 和 B 的 >=2.8.0 接受”。它只判断范围是否有数学交集。比如 ^1.25 和 ~2.9.0 表面都是 2.x，但 ~2.9.0 实际上限是 2.9.9，和 ^1.25 完全无重叠。
实操步骤：
- 去 Packagist 查目标包（如
monolog/monolog）的全部发布版本，重点看v2.9.3、v2.10.0这类边界版本的发布时间和兼容性说明 - 若确认
v2.9.3同时满足两个约束，就在主项目或模块中显式写死："monolog/monolog": "2.9.3" - 再执行
composer update monolog/monolog --with-dependencies，避免波及其他包
最易被忽略的一点：模块升级后，必须检查 git diff composer.lock —— 确认只有预期包及其直系依赖变动，没有意外带进 symfony/polyfill-* 或 psr/log 等间接变更。
