replace字段需写为键值对如"vendor/old-package": "self.version"，且仅当原包已声明replace、项目未显式require该包时才生效；它不卸载已安装包，仅在依赖图中无引用时通过composer update移除。
replace字段怎么写才生效
Composer 的 replace 不是“自动替换”，它只在安装时告诉 Composer：“这个包逻辑上等价于另一个包”，从而阻止被替代包被重复安装。必须同时满足两个条件：原包已声明为 replace，且你的项目里没有显式 require 原包。
- 写法必须是键值对：
"vendor/old-package": "self.version"或具体版本号（如"1.2.0"），不能写成"vendor/old-package": "*"—— 这会被忽略 - 如果旧包本身没设
replace，你只能在自己的composer.json里用conflict+require组合来手动排除和引入新包 -
replace对已安装的旧包无卸载作用；运行composer update后，Composer 会检查依赖图，若发现旧包仅被 replace 关系“覆盖”而无其他依赖引用它，才会真正移除
为什么 composer update 后旧包还在
常见现象：加了 replace、删了 require、跑了 composer update，vendor/old-package 目录却纹丝不动。根本原因通常是依赖链未断开 —— 某个你还留着的包（比如 some-sdk）仍把 vendor/old-package 写在了自己的 require 里。
- 用
composer depends vendor/old-package查谁还依赖它；结果为空 ≠ 安全，某些老旧包可能没申明 autoload，但运行时硬编码引用 - 执行
composer show -t看完整依赖树，定位残留路径 - 如果确认无人依赖，但目录仍在，可能是 Composer 缓存或 lock 文件残留；删掉
vendor和composer.lock后重装（仅限开发环境）
replace 和 provide、conflict 的区别与混用场景
replace 是声明“我顶替谁”，provide 是声明“我能提供什么能力（不一定是同名包）”，conflict 是强硬禁止某包共存。三者常组合使用，尤其迁移时：
- 新包想完全接管旧包行为，用
replace+conflict：例如"replace": {"vendor/old-package": "self.version"}+"conflict": {"vendor/old-package": " - 如果新包只是提供相同接口（如 PSR-Log 实现），但名字完全不同，该用
provide，而非replace—— 否则 Composer 会误判依赖冲突 -
provide不影响安装逻辑，只用于满足其他包的require；replace会影响依赖解析结果，慎用于跨命名空间迁移
PHP 版本或扩展限制导致迁移失败
很多废弃包被替换，是因为新包要求更高 PHP 版本（如从 7.4 升到 8.1）或新增扩展依赖（如 ext-pdo_pgsql）。Composer 不会在 replace 阶段校验这些，而是在安装新包时才报错 —— 错误信息往往指向新包，容易误以为 replace 失效。
- 先运行
composer why-not php:8.1确认当前环境是否满足新包要求 - 检查新包的
composer.json中require.php和require.ext-*字段，比对本地php -v和php -m输出 - 若无法升级环境，别硬套
replace；改用repositories+package类型临时 fork 旧包并打补丁，更稳妥
实际迁移中最容易卡住的，不是 replace 语法写错，而是没意识到它不解决运行时兼容性问题——函数签名变了、配置格式不兼容、甚至日志字段名都换了，这些得靠测试覆盖和手动适配。
