Composer虚拟包是通过replace或provide声明的占位符（如php、psr/log），不下载代码但参与依赖求解；因其不写入composer.lock且易被忽略，常导致升级冲突，需用composer why-not定位并合理约束版本范围。
什么是 Composer 虚拟包，为什么它影响升级策略
Composer 里的虚拟包（virtual package）不是真实存在的包，而是通过 replace 或 provide 声明的“占位符”，比如 php、ext-json、psr/log，或者你自定义的 myorg/core-contracts。它们不下载代码，只参与依赖求解——但正因如此，升级时容易被忽略，导致“明明没动它，却突然不兼容”。
典型翻车场景：你用 replace: {"monolog/monolog": "2.9.0"} 模拟已安装旧版 Monolog，结果升级 Laravel 时，Laravel 的 require 明确要 psr/log ^3.0，而你的虚拟包锁死在 ^1.0，直接卡住求解器，报 your-project-name is not compatible with monolog/monolog 3.0.0 这类看似矛盾的错误。
用 replace 做平滑升级的实操边界
虚拟包本身不能“升级”，但你可以用它控制依赖树的收敛点。关键不是声明一个固定版本，而是让 replace 的版本范围与目标框架兼容性对齐。
- 别写死
"monolog/monolog": "2.9.0"—— 这等于告诉 Composer “全世界只能用这个版本”，会阻断所有需要更高版 Monolog 的包 - 改用宽松约束：
"monolog/monolog": "^2.9 || ^3.0"，给求解器留出空间；如果必须卡主版本，用"monolog/monolog": "2.*"而非精确版 - 若你用虚拟包填补缺失功能（如 polyfill），优先选官方方案：
symfony/polyfill-*已内置provide声明，比手写replace更可靠 -
replace不解决运行时兼容问题——它只骗过 Composer 安装阶段。确保你提供的实现真能响应psr/log接口的所有方法，否则上线就Call to undefined method
composer why-not 是唯一能看清虚拟包怎么拖后腿的命令
当你执行 composer update laravel/framework 失败，且错误里出现“conflict with your requirements or with the packages you are trying to update”，八成是虚拟包在中间挡路。这时候不能猜，得直接查链路：
运行 composer why-not psr/log:^3.0，输出可能类似：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
myapp dev-main replaces psr/log (1.0.0) ├── illuminate/log 5.8.0 requires psr/log (^1.0) └── monolog/monolog 2.9.0 requires psr/log (^1.0 || ^2.0)
这说明你项目里 replaces psr/log (1.0.0) 直接堵死了所有 ^3.0 路径。解决方案不是删 replace，而是把它改成 "psr/log": "^1.0 || ^2.0 || ^3.0"，再重试。
注意：composer show --tree 不显示虚拟包，composer depends 也查不到它们——只有 why-not 和 prohibits 能穿透这层抽象。
真正平滑的升级，靠的是“虚拟包 + 真实 lock 文件”双锁定
很多人以为设了 replace 就万事大吉，结果 CI 环境里跑出不同结果。根本原因是：虚拟包只参与求解，不写入 composer.lock；而 composer.lock 才是最终契约。所以必须两者对齐：
- 先用
composer install生成一份稳定 lock 文件，确认所有真实依赖（包括被虚拟包替代的那些）都落在你预期的版本上 - 把
replace的版本范围设为 lock 文件中对应包的实际版本区间（例如 lock 里psr/log是3.0.0，那replace至少得支持^3.0） - 每次升级前，先
composer update --dry-run验证虚拟包是否仍覆盖新依赖要求；失败就调宽replace，而不是硬顶 - 永远提交
composer.lock—— 它是你虚拟包策略能否落地的唯一证据
虚拟包不是魔法开关，它是你向 Composer 显式声明“我已掌控这部分能力”的方式。错不在它，而在声明和实际能力之间的 gap。填上这个 gap 的，从来不是更复杂的配置，而是 composer why-not 输出的第一行字。
