如何在复杂的依赖冲突中通过Composer命令定位冲突根源

解决Composer依赖冲突，说到底是件磨性子的事。一堆包互相锁死版本，报错信息又绕来绕去，让人头大。不过好在这套工具本身就提供了追查线索的手段，关键是你得知道该从哪里下手。

composer why-not 是第一个必须跑的命令

它什么都不改，就只告诉你一件事：为什么这个版本装不上？输出里的每一行，都对应一个真实存在的硬性约束。比如说，你想装 lara vel/framework:v10.0 却碰了壁，那就跑一句 composer why-not lara vel/framework:10.0.0。结果很可能长这样：

myapp/core dev-main requires lara vel/framework ^9.0
spatie/lara vel-backup v8.0.0 requires lara vel/framework ^9.0
phpunit/phpunit 10.5.0 requires illuminate/support ^9.0

这三行不是平起平坐的关系，得从下往上读。最底下那行是你项目的根 composer.json 提的原生要求，越往上越是传递链条里真正卡住升级的地方。有个细节容易忽略：版本号必须写精确，比如 10.0.0，你要是写成 ^10.0 或 10.*，Composer 直接甩一句 Package not found，白白浪费时间。

用 composer show --tree 看清真实依赖路径

默认的 composer show --tree 只给你看一级依赖，深层的冲突很容易被跳过。真正有价值的是指定包名，再搭配 grep 来过滤。比如这么玩：

• composer show --tree monolog/monolog | grep -A5 -B5 "guzzlehttp/guzzle" —— 看看 monolog 和 guzzle 是否在同一条路径上、版本有没有打架。
• composer show --tree | grep "symfony/console" —— 把所有引入 symfony/console 的包揪出来。特别留意末尾带 (locked to 5.4.32) 的行，这说明那个版本已经被 composer.lock 给焊死了。
• 终端宽度不够的话，建议加个 | less -S，防止缩进被换行打乱，层级关系一眼就能看清。

要是发现同一个包（比如 symfony/console）在不同缩进层级里反复出现，而且版本还不一致（一个 ^5.4，另一个 ^6.0），那冲突基本就锁死在这里了。

composer prohibits 直接锁定“死守旧版”的包

当你想升级某个包但被拦下时，composer prohibits 比 why-not 更对路。比如提示你装不上 guzzlehttp/guzzle:^7.8，那就直接跑：

composer prohibits guzzlehttp/guzzle:^7.8

输出会干脆地告诉你，是谁在拖后腿：

myorg/sdk v2.3.0 requires guzzlehttp/guzzle ^6.5
firebase/php-jwt v6.10.0 requires guzzlehttp/guzzle ^7.2

这里 myorg/sdk v2.3.0 就是证据确凿的源头——不是笼统地说“有依赖冲突”，而是具体到哪个包、哪个版本、提了什么约束。如果输出是空的，意味着没有包显式 require 它，问题可能藏在 replace 或 conflict 字段里，那就得去翻 composer.lock 或对应包的 composer.json 了。

别跳过 --dry-run -v 的末尾日志

composer update --dry-run -v 不会改任何文件，但会完整跑一遍解析流程。关键不在于前面几百行的输出，直接翻到最后 10 行就行：

你会看到类似这样的句子：

Found conflicting requirements for symfony/console: ^5.4 and ^6.0
Because package-a v2.1 requires symfony/console ^5.4, and package-b v3.0 requires symfony/console ^6.0

反复出现的包名，比如 symfony/console、monolog/monolog，就是整场冲突的枢纽。它们被多个上游包绑定了互不兼容的版本。如果 your-project-name 也出现在冲突链里，那你得检查一下自己的 composer.json 是不是某行约束太紧了，比如同时 require 了两个理念相悖的 SDK。

最后说一个容易被忽略的点：require-dev 里的包默认也会参与解析。就算你部署时加了 --no-dev，它们在 update 和 install 阶段依然会影响决策。最典型的就是 phpunit/phpunit 这类工具链包，它可能通过 orchestra/testbench 间接锁死了 lara vel/framework 的版本——你以为是框架依赖出了问题，结果根源竟然在测试工具上。