Composer无法自动解决循环依赖，会直接报错；需通过replace、抽离contracts或重构依赖关系来打破循环。
Composer 无法自动解决真正的循环依赖（A → B → A），它会直接报错并中止安装；所谓“妥协方案”，本质是绕过、打破或重构依赖关系，而非让 Composer 自己“解开死锁”。
识别 composer install 报出的真实循环依赖错误
真正触发循环依赖时，Composer 不会含糊其辞——错误信息明确包含 cycle 和具体包名链。例如：
Dependency resolution failed because of a cycle: mypackage/a → mypackage/b → mypackage/a
注意区分：这不是版本冲突（could not be resolved）或平台不兼容（requires ext-xxx），而是解析器在构建依赖图时检测到有向环。
- 只在
composer update或首次composer install（无composer.lock）时暴露；已有 lock 文件可能掩盖问题 - 如果错误里出现的是 dev-master 或分支别名（如
dev-main），说明你正用不稳定约束，更容易触发环 - 运行
composer depends --tree vendor/package-name可反查谁拉入了该包，辅助定位闭环路径
用 replace 在 composer.json 中主动切断依赖环
当两个包互为必需（比如 core 和 plugin-sdk），又不能合并，最轻量的解法是在其中一个的 composer.json 中声明 replace，告诉 Composer：“我已内置对方功能，无需再装”。
例如，在 myapp/core 的 composer.json 中写：
{
"name": "myapp/core",
"replace": {
"myapp/plugin-sdk": "*"
}
}
这样当 myapp/plugin-sdk 被其他依赖间接引入时，Composer 会跳过安装它，因为已被 core “替代”。
-
replace不影响代码加载逻辑，只是安装时的元数据指令 - 被
replace的包仍可在require-dev中显式安装（用于本地开发测试） - 慎用
replace声明非自己维护的第三方包（如monolog/monolog），会导致不可预期的兼容性断裂
将共享逻辑抽成独立 contract 包，消除双向引用
多数循环依赖源于两个实现包互相调用对方的具体类（A::doX() 调 B::doY()，B::doY() 又调 A::doZ()）。根本解法是引入第三层抽象：
- 新建一个轻量
myapp/contracts包，只含接口（ProcessorInterface）、值对象、简单 trait - 让
myapp/a和myapp/b都require它，并仅依赖接口，不再直接引用彼此的实现类 - 通过构造函数注入或容器配置，在运行时组合具体实现（即依赖反转）
这会让依赖方向变为：A → contracts，B → contracts，消除了 A ↔ B 的边。Composer 解析图立刻变成 DAG（有向无环图）。
关键点：contracts 包的 composer.json 必须不含 autoload 以外的任何依赖，否则它自己又会引入新环。
临时禁用依赖检查的危险操作：--ignore-platform-reqs 无效，--no-update 不适用
有人误以为加参数能绕过循环依赖检查——实际不行。--ignore-platform-reqs 只跳过 PHP 版本、扩展等平台约束；--no-update 是跳过更新 lock 文件，但解析阶段早已失败。
唯一“强行继续”的方式是手动编辑 composer.lock，删掉引发环的包条目，再运行 composer install --no-scripts。但这等于放弃依赖一致性保障：
- 下次别人执行
composer update仍会失败 - CI 环境大概率因 lock 文件校验失败而中断
- 你删掉的包若被运行时反射调用，会直接抛
Class not found
这类操作只应在调试环境临时验证某段逻辑，绝不可提交到仓库或用于部署。
循环依赖不是配置问题，是架构信号。真正难处理的从来不是 Composer 报错本身，而是团队对“哪个包该提供什么能力”的认知分歧——这没法靠命令行参数修复。
