Composer循环依赖必须从代码结构打破，无法绕过；确认方法包括报错信息含嵌套指向自身、--dry-run反复跳转、卡在Resolving dependencies超30秒、depends --tree显示闭环路径；破环方式有抽离公共契约、运行时解耦、降级为可选依赖；隐式循环常由autoload与require-dev组合引发。
Composer 遇到循环依赖，不会给你绕过去的机会——它直接报错退出，且不提供 --force、--skip-cycle 这类开关。这不是配置没写对，而是依赖图里出现了 A → B → A 这种逻辑闭环，必须从代码结构上打破。
怎么确认是循环依赖，不是普通版本冲突
关键看报错信息和回溯行为：
- 报错中出现
Package a depends on b, which depends on a或类似嵌套指向自身描述，基本实锤 - 执行
composer update --dry-run -v，最后几行反复出现同一组包来回跳转（如vendor/a → vendor/b → vendor/a） -
composer install卡在Resolving dependencies超过 30 秒，且无网络请求日志——SAT 求解器正在死循环里打转，不是慢，是绕不出去 - 运行
composer depends --tree vendor/a，输出中出现vendor/a ← vendor/b ← vendor/a（注意箭头方向是“被谁依赖”）
用 composer depends --tree 定位真实闭环路径
这是唯一靠谱的诊断入口，但有硬性前提：
- 必须在已成功执行过
composer install的项目里运行，否则依赖图不完整 - 必须加
--tree参数，否则只显示一级依赖，看不到闭环 - 如果提示
Package not found，说明该包根本没进composer.lock——先删掉vendor/和composer.lock，再跑composer update --dry-run观察第一步失败点 - 临时注释掉
require-dev下所有非核心工具（如phpunit/phpunit、phpstan/phpstan），再试一次composer update；很多“循环”其实是测试工具反向加载了你的src/
三种真正有效的破环方式，没有第四种
所有靠谱方案都指向一个目标：让依赖方向变成单向。别试图用 replace 或 provide 伪装版本兼容——这只会让 autoload 更混乱。
-
抽离公共契约：把双方共用的接口、DTO、异常类拎出来，建新包
myorg/contracts；它的composer.json中"require": {}应为空；myorg/core和myorg/api都只require "myorg/contracts": "^1.0"，并删掉彼此的require -
运行时解耦：A 不再
new B()或use BSomeClass，而是定义interface ServiceInterface（放在契约包），B 实现它，A 通过容器或工厂获取实例；此时 A 的composer.json里必须彻底删掉对 B 的require -
降级为可选依赖：如果 B 只在 A 的测试中用（比如 Mock 数据），就移到
require-dev；如果是增强功能（如导出 Excel），改用suggest字段提示用户手动安装
最容易被忽略的隐式循环：autoload + require-dev 组合
你以为只是开发依赖，结果它悄悄污染了主依赖图：
- 检查
autoload配置：如果"psr-4": {"App\": "src/"}，而src/里用了require-dev包的类（比如PHPUnitFrameworkTestCase），Composer 就会把它当作生产依赖来解析 - 确认
autoload-dev是否只覆盖tests/或stubs/，且命名空间没和autoload重叠 - 运行
composer dump-autoload --no-dev后再试composer update，能快速验证是否由 autoload 引入的隐式依赖导致
真正卡住的往往不是哪一行 require，而是 autoload 和 require-dev 在背后悄悄握手——重构前，先关掉 --no-dev 看看问题还在不在。
