Composer虚拟包是通过provide或replace声明的占位符，不提供实际代码，仅影响依赖解析；它易引发隐式循环依赖，因多个包可能互相声明提供同一能力（如psr/log），导致SAT求解器陷入版本选择僵局。
Composer 虚拟包本身不解决循环依赖，反而常是隐式循环的放大器——它让“逻辑上不该共存”的包在依赖图里强行并存，导致 composer update 卡死或 composer why-not 输出混乱。
虚拟包（virtual package）是什么，为什么它会藏匿循环
虚拟包不是真实发布的包，而是通过 replace 或 provide 字段声明的“占位符”，比如 "symfony/polyfill-mbstring": "*" 在 composer.json 中用 "provide": {"ext-mbstring": "*"} 告诉 Composer：“我提供了 mbstring 扩展功能”。但它不参与自动加载、不提供类，只影响依赖解析。
问题出在：多个虚拟包可能互相声明替代同一底层能力（如 ext-json、psr/log），而真实包又同时 require 它们——这时 SAT 求解器会在“选 A 还是选 B 替代 ext-json”之间反复横跳，形成逻辑闭环。
- 常见组合：
symfony/polyfill-json+ext-json+ 某个强制要求psr/log ^2.0但又被monolog/monolog（requirepsr/log ^1.0）间接拉入的包 - 表现不是报错，而是
composer update --dry-run -v最后几行反复出现同一组provide链路，例如：vendor/a → provides psr/log → vendor/b → requires psr/log ^1.0 → vendor/a - 虚拟包不会出现在
composer show --tree的主干路径里，但会出现在composer show vendor/a的provides字段中——必须主动查
怎么确认虚拟包是不是循环元凶
别猜，用命令直接剥开它的外壳：
- 运行
composer show --platform，看哪些扩展被标记为(provided)，再检查这些提供者是否在composer.json的require或require-dev里被显式引入 - 对可疑虚拟包执行
composer why-not vendor/virtual-package:dev-main，如果输出里出现“because it provides X, and Y requires incompatible X”，说明它正卡在提供能力与需求版本的夹缝中 - 重点检查
composer.lock中该虚拟包的version字段：如果是9999999-dev或dev-main，说明它没被锁定到稳定语义版本，每次update都可能触发重新求解
安全处理方式：替换、降级、隔离三选一
虚拟包不能删，但可以控制它怎么参与解析：
- 若项目已装
ext-mbstring，就删掉symfony/polyfill-mbstring的require，改用conflict显式排除："conflict": {"symfony/polyfill-mbstring": "*"}——避免它和真实扩展抢“提供权” - 把
provide类虚拟包降级为require-dev：比如phpunit/phpunit提供phpunit/phpunit，但它本就不该在生产环境参与运行时依赖，移到require-dev后，composer install --no-dev就彻底绕过它 - 用
--with临时覆盖：升级某个包时加composer update monolog/monolog --with=symfony/polyfill-json:^1.0，强制指定虚拟包版本，防止求解器自由试探
最易被忽略的一点：虚拟包的 provide 是全局生效的，哪怕你没在 require 里写它，只要某个已安装包的 composer.json 声明了它，它就在整个依赖图里起作用。排查时得连 vendor/*/composer.json 一起 grep provide。
