循环依赖指多个包相互引用导致 composer 无法解析，表现为安装时报错“Circular dependency detected”。可通过重构代码（如提取公共包、使用接口注入）、调整版本约束（避免严格依赖 dev 分支）及利用 composer depends 或 show –tree 命令分析依赖树来解决。关键在于明确包职责边界，降低耦合。
Composer 中的循环依赖指的是两个或多个包互相依赖，导致无法正确解析依赖关系。这在 php 项目中虽然不常见，但一旦出现会导致安装或更新失败。解决这类问题需要从设计和配置两方面入手。
理解循环依赖的表现
当你运行 composer install 或 update 时，如果看到类似以下错误：
Circular dependency detected: package-a -> package-b -> package-a
说明存在循环引用。Composer 无法确定加载顺序，因此拒绝执行操作。
重构代码结构打破依赖
最根本的解决方式是重新审视项目架构，避免强耦合：
- 将共用的功能提取到第三个独立的包（例如：shared-utils），让原来的两个包都依赖它
- 使用接口与依赖注入，让一个包只依赖抽象而非具体实现
- 检查是否可以把部分逻辑上移或拆分，降低模块间的相互引用
比如 A 包调用了 B 的某个服务，而 B 又需要 A 的数据模型，可以将数据模型移到公共包中，或者通过事件机制解耦。
调整版本约束减少冲突
有时循环依赖是因为版本约束不合理导致的临时现象：
- 确认各包的 require 字段是否指定了过于严格的版本（如 dev-main）
- 尝试使用更宽松的稳定版本号（如 ^1.0）避免开发分支互相锁定
- 检查是否有通过 repositories 引入本地包造成隐式循环
适当使用 replace 或 provide 字段也能帮助 Composer 更好地解析替代关系。
利用 Composer 插件或脚本辅助分析
可以通过工具定位依赖路径：
- 使用 composer depends package/name 查看谁依赖了指定包
- 运行 composer show –tree 展示完整的依赖树，手动排查环路
- 结合静态分析工具（如 PHPStan 配合插件）发现潜在的设计问题
提前发现问题比等到报错更高效。
基本上就这些。关键在于保持包职责清晰，避免互相“你中有我，我中有你”。合理划分边界，循环依赖自然就消失了。