Composer 2.2+ 收紧 replace 语义，仅用于依赖解析阶段的“包存在性判断”，不再自动替换或覆盖版本；需改用 provide + 显式 require + conflict 组合替代，并检查命名空间、配置文件及运行时类检查等硬性依赖点。
为什么 replace 不再可靠？
Composer 2.2+ 对 replace 的语义做了收紧：它现在只影响依赖解析阶段的“包存在性判断”，不再自动触发包替换或版本覆盖。如果你曾用 replace 让 old-package 假装成 new-package 来绕过冲突，现在大概率会失败——composer install 可能直接报 Package old-package is abandoned 或因版本不匹配中断。
根本原因是 Composer 不再把 replace 当作“别名重定向”，而仅视为“此包已由其他包逻辑接管”。真实依赖仍需显式声明。
用 provide + 显式 require 替代 replace
迁移核心是把“隐式替代”转为“显式提供+引用”：
- 在新包（如
new-vendor/new-package）的composer.json中，用provide声明它能提供旧包能力："provide": { "old-vendor/old-package": "^1.0" } - 在项目根
composer.json中，删掉对old-vendor/old-package的require，改为显式 require 新包："require": { "new-vendor/new-package": "^2.0" } - 如果旧包被其他依赖间接引入，加
conflict阻止残留："conflict": { "old-vendor/old-package": "*" }
这样既保留兼容性提示（provide 会让 Composer 知道能力已就绪），又避免解析歧义。
迁移时必须检查的三个硬性依赖点
光改 composer.json 不够，以下位置常被忽略但会导致运行时报错：
-
use语句和类名引用：旧包的命名空间（如OldVendorOldPackageHelper）不会自动映射到新包，必须手动批量替换为新命名空间 - 配置文件中的类名字符串：Laravel 的
config/app.php、Symfony 的services.yaml等，凡写死旧类名的地方都得同步更新 - 运行时 class_exists() 或 interface_exists() 检查：若代码里有类似
class_exists('OldVendor\OldPackage\Contract')，需改成检查新接口，或加class_alias()兜底（仅限过渡期）
废弃包迁移后仍报错的典型场景
即使 composer install 成功，以下情况仍会出问题：
- Autoload 冲突：两个包注册了同一命名空间（如都声明
"psr-4": {"OldVendor\": "src/"}），Composer 会按加载顺序覆盖，导致类找不到——必须确保旧包完全从vendor/中移除（检查composer.lock是否还有残留） - PHP 版本或扩展依赖变化：新包可能要求
ext-gmp或 PHP 8.1+，而旧环境未满足，错误信息常为Class not found而非明确提示——用composer why-not php:8.1和composer show new-vendor/new-package核对 require 项 - 插件或脚本钩子残留：旧包的
scripts（如post-install-cmd）若还留在composer.json里，执行时会报Command "old:setup" is not defined
最稳妥的方式是：删掉 vendor/ 和 composer.lock，再 composer install 重装，而不是增量更新。
