下游项目执行 composer update 失败是因为 composer 不识别旧包名到新包名的映射，replace 字段仅在当前包依赖解析时生效，对下游 require 无效；需通过 repositories + package 类型伪造旧包，指向新包分发源，并严格匹配版本与 autoload。
为什么下游项目执行 composer update 会失败
因为 Composer 完全不识别“旧包名 → 新包名”的映射关系，replace 字段只在**当前包的依赖解析阶段生效**，对下游项目的 require 条目毫无作用。下游项目 composer.json 里还写着 "oldvendor/oldpackage": "^2.3"，而该包已从 Packagist 下架或改名，composer update 就会卡在 “Could not find package oldvendor/oldpackage” 或直接报 404。
如何让下游项目无需改代码就能继续 install
靠 repositories + package 类型伪造一个“假旧包”，把请求重定向到新包源。这不是 hack，是 Composer 官方支持的过渡方案。
- 在下游项目根目录
composer.json的顶层加"repositories"数组（注意不是嵌套在config或require里） - 类型必须设为
"package"，不能用vcs——否则无法伪造包名 -
"name"必须严格写成旧包名（如"oldvendor/oldpackage"），"dist"指向新包的 ZIP 或 TAR 包 URL（推荐用 GitHub Release 的原始下载链接） -
"version"要和下游项目当前锁死的版本一致（查composer.lock里该包的version字段），否则版本不匹配仍会失败
示例片段：
"repositories": [
{
"type": "package",
"package": {
"name": "oldvendor/oldpackage",
"version": "2.3.1",
"dist": {
"url": "https://github.com/newvendor/newpackage/releases/download/2.3.1/newpackage-2.3.1.zip",
"type": "zip"
},
"autoload": {
"psr-4": { "OldVendor\OldPackage\": "src/" }
}
}
}
]
replace 字段写在哪、怎么写才对下游有效
replace 必须写在**新包自己的 composer.json 中**，且下游项目必须已安装该新包（即 require 里已改成新包名）。它不是给下游项目看的，而是告诉其他包：“别再装旧包了，我就是它的替代品”。
- 写法必须精确：例如
"oldvendor/oldpackage": "2.3.1"，不能写"*"或"self.version"—— 后者只在新包内部解析时有效，下游项目不会读取 - 版本号必须覆盖下游实际使用的版本，比如下游锁的是
2.3.1，你写"oldvendor/oldpackage": ">=2.3.0 才能命中 - 如果下游项目仍有其他包间接依赖
oldvendor/oldpackage（用composer depends oldvendor/oldpackage验证），仅靠replace不够，必须配合repositories或等上游包升级
autoload 映射错位会导致 Class not found
即使 repositories 和 replace 都配对了，只要新包的 autoload 没按旧命名空间声明，use OldVendorOldPackageFoo 就会报错——Composer 装对了包，但 autoloader 根本不加载那个路径。
- 新包
composer.json中autoload.psr-4必须显式保留旧命名空间映射，例如："OldVendor\OldPackage\": "src/" - 如果新包同时支持新命名空间（如
NewVendorNewPackage），可加双映射，但旧映射不可删 - 下游项目执行
composer dump-autoload是必须步骤，尤其在首次切换后；否则缓存的 autoload 文件仍指向旧路径
真正的兼容性不在包名替换，而在类加载路径是否被真实覆盖。所有配置都正确时，composer install 成功只是第一步，vendor/autoload.php 是否能把 OldVendorOldPackage* 正确解析到新包的 src 目录，才是最后一道关卡。
