Composer不管理命名空间，仅负责自动加载；PSR-4映射冲突源于多包声明相同前缀导致类覆盖，引发“Cannot declare class”错误；可用exclude-from-classmap隔离干扰文件、replace/conflict声明兼容边界，并用composer dump-autoload -o和composer show -t调试。
Composer 本身不管理 PHP 命名空间，它只负责自动加载类文件；所谓“命名空间冲突”，实际是 autoload 规则配置不当或包内类定义不合理导致的类加载覆盖或重复声明错误。
为什么 composer.json 的 psr-4 配置会引发冲突
PSR-4 映射是“前缀 → 路径”的静态映射，Composer 不校验命名空间是否真实存在、也不检查多个包是否映射到同一命名空间。一旦两个包在 autoload 或 autoload-dev 中声明了相同命名空间前缀，就会出现后加载的规则覆盖前加载的——但 PHP 解析器只允许一个类被定义一次，运行时直接报 Fatal error: Cannot declare class XXX, because the name is already in use。
常见诱因：
- 本地开发包和线上同名包（如都用
"MyLib\": "src/"）未隔离 - 第三方包误将测试类或 stub 类暴露进
autoload（而非仅autoload-dev） - 自定义包中使用了与知名包相同顶级命名空间（如
Monolog\、Doctrine\）
如何用 exclude-from-classmap 隔离干扰文件
某些包目录里混着旧版类、示例类或适配器 stub，它们有合法命名空间但不该参与自动加载。与其改源码，不如在自己的 composer.json 中主动排除：
{
"autoload": {
"psr-4": { "App\": "src/" }
},
"autoload-dev": {
"psr-4": { "App\Tests\": "tests/" }
},
"extra": {
"exclude-from-classmap": [
"vendor/some/package/src/legacy/",
"vendor/some/package/src/ExampleController.php"
]
}
}
注意：exclude-from-classmap 只对 classmap 类型生效；对 psr-4 无效——但它能防止 Composer 在生成优化类映射时把不该加载的文件扫进来，间接降低冲突概率。
用 replace 和 conflict 主动声明兼容边界
当你提供一个替代包（如 fork 后修复 bug），必须明确告诉 Composer：“我代替谁”“谁不能共存”。否则用户 require 两个包时，Composer 可能静默安装并导致运行时类冲突。
正确做法：
- 在 fork 包的
composer.json中加"replace": { "original/package": "self.version" } - 若你的包与某版本存在不可调和的命名空间重叠（如都注册了
Vendor\Core\），加"conflict": { "bad/package": ">=2.0.0" } - 执行
composer update时，Composer 会检查这些字段并拒绝安装冲突组合
调试命名空间加载路径的实用命令
当怀疑类没按预期加载或被覆盖，别猜，直接查 Composer 生成的映射：
-
composer dump-autoload -o --no-dev：生成优化后的vendor/composer/autoload_classmap.php，打开它搜类名，看它指向哪个文件 -
composer show -t：显示依赖树，确认是否有两个包同时声明了相同命名空间映射 - 临时加日志到
vendor/autoload.php开头，打印debug_backtrace()，观察是哪个require触发了冲突类的首次加载
最易忽略的是：Composer 的 autoload 机制完全依赖文件系统路径与命名空间字符串的字面匹配，大小写敏感、尾部反斜杠是否一致（App\ vs App）都会导致映射失效或错位——这种细节问题不会报错，只会让类“找不到”或“被跳过”。
