如何排查Composer依赖解析中的死循环问题？

本文共计1004个文字，预计阅读时间需要5分钟。

Composer解析死循环并非‘慢’，而是求解器在无限回溯——CPU持续95%、内存每秒涨50MB、composer update --dry-run -v，最后几行反复出现同一组包名，基本可以确定是闭环卡死了。

看 composer update --dry-run -v 的“临终遗言”

这个命令不改任何文件，但完整走一遍 SAT 求解流程，失败前会打印它最后尝试的组合和立即 reject 的原因。这不是日志，是求解器的决策痕迹。

• 重点盯最后 5–10 行：如果反复出现 vendor/a → vendor/b → vendor/a 这类嵌套，就是强循环信号
• 留意 “Rejecting vendor/b because it requires vendor/a ^2.0” 这类语句——而当前项目锁的是 vendor/a:1.9，说明版本约束在闭环里互相拉扯
• 如果某包名连续出现 ≥3 次（比如 myorg/core 被 myorg/api、myorg/utils、phpunit/phpunit 分别引入），大概率是间接环

用 composer depends --tree 实锤闭环链

这是目前唯一能直接看到闭环路径的命令，但有两个硬前提：项目必须已有有效的 composer.lock，且必须加 --tree 参数。

• 运行 composer depends myorg/core --tree，如果输出含 myorg/core ← myorg/api ← myorg/core，就是闭环实锤
• 如果报 Package not found，说明该包根本没进 composer.lock——删掉 vendor/ 和 composer.lock，再跑 composer update --dry-run -v 看第一步失败点
• 别只查一级依赖：composer depends myorg/core（无 --tree）只会显示直接上游，漏掉 A→C→B→A 这类多跳环

警惕 autoload + require-dev 构成的隐式循环

最常被忽略的“循环”根本不在 require 字段里，而是测试工具通过自动加载把你的代码反向拉进了它的运行时上下文。

• 检查所有 require-dev 包的 composer.json，重点搜 ../、../../、src/、tests/ ——比如 phpunit/phpunit 的 "autoload": {"psr-4": {"App\": "../src/"}} 就会让它加载你的 src/
• 确认你自己的 autoload-dev 没把 vendor/ 下的路径写进去，否则 Composer 会认为“我依赖我自己”
• 临时注释掉非核心 require-dev 条目（尤其是 infection/infection、phpstan/phpstan 插件），再试 composer update；很多“死循环”只是测试包在作祟

别删 composer.lock 强制重装

直接删 composer.lock 再跑 composer install 不是解法，是制造新问题——它绕过所有版本一致性保障，极大概率导致生产环境行为漂移。

• composer update --lock 才是安全操作：不升级包、不改 vendor/、只刷新 composer.lock 结构和哈希，适用于改了 platform 或 minimum-stability 后同步 lock 文件
• 遇到 cycle detected，优先用 composer depends --tree 定位谁在引入可疑包，再用 composer why-not vendor/package:version 查具体哪条路径卡死
• 真正破环只有三种：抽离契约包（myorg/contracts）、运行时解耦（接口 + DI）、或把仅测试用的依赖降级到 require-dev ——没有“跳过”选项，也没有“强制安装”参数

闭环往往藏在 autoload 路径和 require-dev 的交叉里，而不是明面上的 require 字段；composer depends --tree 输出里那个自指路径（比如 myorg/core ← myorg/api ← myorg/core），才是你该盯着改代码的地方。