PHP Composer 依赖冲突怎样从约束定位

PHP Composer 依赖冲突的定位重点，是把“某个包装不上”还原成一组版本约束的交集问题。先看 composer.json 的直接要求，再看传递依赖和 composer.lock 当前锁定的版本，最后用 prohibits 或 why-not 指出究竟是谁排除了目标版本。这样修复时不会因为一次全量更新而引入一串无关变化。

官方地址：https://getcomposer.org/

一、先区分直接约束、传递约束和锁定版本

Composer 的“版本”通常是约束表达式，而不是已经安装的唯一版本。比如 ^1.4 允许兼容的后续版本，1.4.2 则只接受这个版本；多个范围用空格表示 AND，用 || 表示 OR。一个项目可能直接要求 psr/log，同时又通过框架间接要求它，最终求解器要找的是所有约束的共同交集。

composer.lock 存在时，composer install 会按锁定结果安装，不会因为仓库出现了新版本就自动重新选择。因此“昨天能装、今天改了 composer.json 不能装”时，要分别看声明文件和锁文件，不能只盯着 vendor 目录。

二、用 prohibits 找到真正的阻塞包

看到冲突信息后，先把“想升级到哪个版本”明确下来，再询问谁阻止了它。Composer 官方命令 prohibits 也可用 why-not 调用，-t 会展开递归依赖树：

# 查看哪些包阻止目标依赖进入 2.0，并展开传递依赖链
composer prohibits vendor/package 2.0 -t

# 用别名得到同一类阻塞信息，便于排查升级失败
composer why-not vendor/package 2.0 -t

# 如果怀疑是 PHP 运行时平台要求冲突，直接检查平台版本
composer prohibits php 8.3

输出中看到 requires，通常表示某个包的下限或上限不允许目标版本；看到 conflicts，则是包显式排斥它。若目标版本其实已经写进锁文件，先确认命令是否只是在改动 composer.json 后触发了锁文件过期，而不是误判为仓库不可用。

三、比较约束交集，再决定改谁

不要把“改成更宽的范围”当成通用修复。^1.4、~1.4 和精确版本的上界不同，稳定性标记也会影响候选集合。生产项目通常先保留兼容边界，再用 prohibits 反向找出需要升级的上游包；只有确认兼容性后，才把范围扩大。

四、用最小更新重建可复现结果

确认修复方向后，不要立刻执行全量 composer update。先针对冲突包更新，并在确有必要时带上它的依赖：

# 只重算目标包，减少无关依赖漂移
composer update vendor/package

# 目标包的传递依赖也需要一起调整时，再扩大更新范围
composer update vendor/package --with-dependencies

# 更新完成后检查声明文件与锁文件是否同步
composer validate
# 查看最终依赖树，确认阻塞包已不再落入冲突链
composer depends vendor/package -t

如果冲突来自根项目的直接约束，修改 composer.json 后再更新；如果来自某个上游包，则应优先升级或替换那个上游包。更新成功后提交 composer.json 与 composer.lock，让 CI 和其他开发机使用同一组解析结果。

五、把一次排错沉淀成检查清单

我处理 Composer 冲突时会按这个顺序留下记录：目标包和目标版本、直接约束、prohibits 输出、平台要求、锁文件是否过期、实际修改的包，以及 composer validate 的结果。这个顺序能把“版本不存在”“约束不相交”“平台不满足”和“锁文件未同步”分开。

常见问题

composer install 为什么没有安装最新版本？

项目有 composer.lock 时，install 以锁文件的精确结果为准。需要重新求解依赖时使用 update，并审查生成的锁文件变化。

prohibits 查不到冲突怎么办？

先确认目标包名和版本约束写法，再加 -t 展开递归关系；若怀疑运行环境，直接检查 php 或具体扩展的 platform requirement。

能不能直接删除 composer.lock？

应用项目不建议把删除锁文件当第一步，因为它会让整个依赖图重新选择版本。先用命令定位冲突，只在明确需要重新解析且能完成完整回归时再重建。

Composer 依赖冲突不是“哪个包坏了”的猜谜题，而是约束交集为空或锁定结果与新声明不一致。沿着直接约束、阻塞链、平台要求和最小更新四层排查，通常可以用一次可解释的改动恢复安装。