Composer 报“Package is already registered”错误是因为 name 字段是注册表唯一键，同名包（即使来自不同仓库）在加载阶段即冲突；解决需改名、更新 autoload 映射、配置 repositories 和 replace，并确保代理类或封装隔离到位。
Composer 本身不解决命名冲突，它只报错；类名/包名冲突必须靠改名、替换或封装来隔离，没有“自动修复”这回事。
为什么 Composer 报 Package … is already registered 就停住？
因为 name 字段是 Composer 内部注册表的唯一键，不是路径、URL 或版本号决定归属。两个不同 Git 仓库只要 composer.json 里都写着 "name": "monolog/monolog"，解析器在内存加载阶段就直接抛异常，根本不会走到 autoload 或安装逻辑。
- 错误信息典型形式：
Package monolog/monolog is already registered或is listed multiple times -
repositories类型（vcs/package）不影响校验——同名即冲突 -
alias字段不能绕过这个检查，它只影响版本匹配，不改name - 临时删
vendor/或硬改composer.lock只能骗过一次，下次composer update立刻还原
fork 包必须改 name 才能被正确识别
你 fork 了 monolog/monolog 并打了 patch，但没改 composer.json 中的 name，那它和官方包在 Composer 眼里就是同一个东西，不可能共存。
- 新
name必须带组织前缀，例如"acme/monolog"，避免用"monolog_custom"这类易与未来官方包重名的写法 - 改完
name后，必须同步检查并更新该包自身的autoload配置：如果命名空间从Monolog\改成Acme\Monolog\，psr-4映射也得跟着改 - 主项目中要通过
repositories指向你的新源，并在require里用新name，例如："acme/monolog": "dev-main" - 若其他依赖（如
laravel/framework）间接依赖原monolog/monolog，你还得在主项目composer.json中加replace：
"replace": {
"monolog/monolog": "*"
}
但注意：replace 不自动加载你的代码，类路径还得靠 autoload 正确映射。
autoload 配置错位是 Class not found 的真正原因
很多人加了 replace 就以为搞定了，结果运行时报 Class not found。这不是 Composer 冲突没解，而是 autoloader 根本找不到类文件。
-
exclude-from-classmap只对classmap生效，对psr-4无效；别指望它“屏蔽”一个 PSR-4 加载的冲突类 - 用
psr-4显式重映射 + 目录隔离可行，但要注意：src/VendorA/Helper.php文件顶部必须改成namespace VendorA;，否则映射失效 - 软链接方式需确认部署环境支持；复制方式要手动同步上游更新，容易漏
-
class_alias()是运行时补丁，会导致反射失败、IDE 跳转失效、类型提示丢失，生产环境禁用
代理类封装是最稳妥的运行时隔离方案
当你既不能改上游包命名空间，又不想碰 autoload 映射，代理类是唯一不破坏兼容性的做法。
- 不修改任何第三方代码，也不动
composer.json的 autoload 段 - 新建一个
MyApp\Cache\VendorACache类，内部new \VendorA\Cache()，把方法一层层转发过去 - 对外暴露统一接口（比如实现
CacheInterface），让业务代码只依赖你的代理类 - 后续升级上游包时，只需调整代理类内部调用，上层完全无感
最容易被忽略的是：autoload 和 replace 是两套独立机制，改了包名不等于类能加载，改了 replace 不等于命名空间自动迁移。每个环节都得单独验证，缺一不可。
