Composer 的循环依赖真会报错，当依赖图无法拓扑排序（如 A→B→C→A）时抛出“Circular dependency detected”错误；常见于 require-dev 反向引入、互相 require 或 autoload-dev 间接触发。
什么是 Composer 的循环依赖，它真会报错吗？
Composer 本身不会主动检测或阻止循环依赖，它只在安装/更新时按依赖图拓扑排序，一旦遇到无法线性排序的情况（比如 A → B → C → A），就会抛出 Unresolvable dependencies 或更具体的 Circular dependency detected 错误。但注意：这种循环往往不是直接的 A → A，而是通过多层 require 形成的隐式闭环。
常见诱因包括：
- 包 A 在
require中声明了包 B，而包 B 的require-dev又反向引入了包 A（开发依赖被误带入生产依赖图） - 两个包互相
require对方（极少见，但私有包协作中可能因版本约束松动意外触发） - 某个包在
autoload-dev中加载了本应仅用于测试的类，却在运行时被其他包的自动加载逻辑间接触发
如何定位真正的循环链？用 composer show -t
composer show -t 是最直接的诊断命令，它输出当前项目的完整依赖树（topological order）。重点不是看全量，而是聚焦报错时提到的几个包名，手动向上/向下追溯路径。
实操建议：
- 先运行
composer update --dry-run -v，观察 verbose 日志里卡在哪一步、哪两个包之间反复跳转 - 对疑似包单独执行
composer show -t vendor/package-name，看它的依赖是否意外拉入了上游 - 检查
composer.json中所有require-dev条目——它们默认不参与生产安装，但如果用了--with-all-dependencies或某些 CI 脚本强制启用，就可能激活隐藏路径
打破循环的三种有效手段
解决思路不是“删依赖”，而是切断非必要依赖流。以下方法按优先级排列：
-
把开发依赖移出 require-dev：如果某个包只在测试中用到（如
phpunit/phpunit），但被写进了主require，立刻移到require-dev；反之，若某包确需运行时存在，就别放在require-dev里还让其他包通过 autoloading 间接依赖它 -
用 replace 替换掉冲突包：例如 A 和 B 都 require C，但 C 的某个版本与 A/B 不兼容，可在根
composer.json中加"replace": {"vendor/c": "*"}，再手动 require 兼容版本，绕过自动解析 -
拆分代码，消除运行时耦合：如果 A 和 B 真需互相调用，说明职责边界模糊。把共用逻辑抽成第三个包 C，让 A 和 B 都
requireC，而非彼此依赖——这是最干净的长期解法
autoload-dev 导致的“伪循环”最容易被忽略
这是进阶场景中最隐蔽的问题：你的代码没循环，但 Composer 的自动加载机制“制造”了循环。典型表现是 Class not found 错误出现在 vendor/autoload.php 初始化阶段，且堆栈指向某个 tests/ 下的文件。
原因在于：autoload-dev 的 PSR-4 映射会被合并进全局 autoloader，一旦某个包的测试类名和另一个包的生产类名冲突（或被错误引用），就会在加载时触发无限递归查找。
排查步骤：
- 临时注释掉根项目
composer.json中的autoload-dev段，运行composer dump-autoload，再测试是否还报错 - 检查所有被
autoload-dev覆盖的路径下，是否存在与生产代码同名的类（比如都叫Helper），或是否在src/中require了tests/下的文件 - 确保
autoload-dev不包含任何会被生产环境代码直接 new 或 static call 的类
真正棘手的循环，往往藏在 autoload 配置和开发/生产环境混用的边界上。
