Composer 循环依赖错误指多个包在 require 中互相依赖导致解析失败，如 A→B→A；需用 composer show -t 定位闭环，通过提取公共包、接口解耦或降级为 require-dev/suggest 打破循环，并以 composer update --dry-run 验证。
什么是 Composer 循环依赖错误？
Composer 报错 Dependency resolution failed 或具体提示 Circular dependency between packages A and B，说明两个或多个包在 composer.json 的 require 字段中互相声明了对方为依赖。Composer 无法确定安装顺序，直接终止解析。
检查循环依赖的准确位置
运行 composer depends --tree <package-name> 可以逆向追踪依赖链。但更有效的是用 composer show -t 查看完整依赖树，然后人工定位闭环路径——比如 A → B → C → A 或更隐蔽的 A → B → A（B 直接 require A）。
- 注意：某些循环是间接的，比如 A require B，B require C，C require A，此时三者都需检查各自的
composer.json - 第三方包若已发布稳定版，其
composer.json通常不可改；问题大概率出在你自己的私有包或本地开发包中 - 使用
composer validate确保每个包的composer.json语法合法，避免因格式错误导致解析异常被误判为循环
打破循环的三种可行方式
核心原则：让依赖方向变成单向。不能靠“忽略警告”或降级 Composer 版本解决。
-
提取公共逻辑到新包：A 和 B 都需要的类/接口/工具函数，应抽离成独立包 C，然后 A 和 B 各自
require C，移除 A↔B 的直接依赖 - 用接口解耦 + 运行时注入：A 需要调用 B 的某功能，但不硬依赖 B 的具体实现。定义接口在 A 中（或共享包），B 实现该接口，A 通过 DI 容器或工厂获取实例——此时 A 不再 require B，只 require 接口所在包
-
将 B 的能力降级为可选（
require-dev或suggest）：如果 B 的功能仅用于 A 的测试或 CLI 工具场景，移到require-dev；若属增强功能，改用suggest字段提示用户按需安装，而非强制依赖
验证修复是否生效
修改后必须执行完整流程验证，不能只跑 composer install：
composer update --dry-run
加上 --dry-run 参数可预检依赖解析是否成功，不实际写入 vendor 或 composer.lock。若仍报循环，说明还有隐藏依赖未清理干净——常见于：autoload-dev 引入了测试类却反向引用主代码、scripts 中调用了其他包的二进制命令、或 repositories 指向了未更新的旧版本包。
真正容易被忽略的是：私有 Packagist 仓库缓存了旧版 composer.json，即使你本地改了，Composer 仍拉取缓存中的元数据。此时需手动清除 Composer 缓存：composer clear-cache，再重试。
