命名空间重叠必然导致类加载劫持，而非可能出问题；只要两个psr-4映射指向同一前缀（如"app\": "src/"），首次加载走前一路径，二次new即fatal error: cannot declare class。
命名空间重叠不是“可能出问题”，而是只要两个 psr-4 映射指向同一前缀（比如都配了 "App\": "src/"），就必然导致类加载劫持——PHP 第一次加载某个 AppHelper 时走的是前一个路径，第二次 new AppHelper() 就直接 Fatal error: Cannot declare class，没有预警、不可捕获。
怎么快速确认是不是 PSR-4 前缀撞车了
别等报错再查，先看 autoload 注册结果：
- 运行
composer dump-autoload -v，搜索你的命名空间关键词（如App\），如果输出里出现两行以上App\ => ...，就是实锤撞车 - 打开
vendor/composer/autoload_psr4.php，用编辑器搜索目标类名（如Helper），如果匹配到多个路径，说明 Composer 把它从不同包里都扫进来了 - 检查所有依赖包的
composer.json，尤其注意autoload和autoload-dev字段——很多第三方包把测试类或 stub 文件错误地放进autoload而非autoload-dev
exclude-from-classmap 对 PSR-4 完全无效
exclude-from-classmap 只在生成 classmap 时起作用，而 PSR-4 是运行时路径映射，两者机制完全不同。写成这样毫无意义：
"exclude-from-classmap": ["Helper.php"]
正确做法是：
- 路径必须是相对于项目根目录的完整路径，且带扩展名：
"src/Deprecated/Helper.php"✅ - 如果是目录，末尾必须加斜杠：
"legacy/"✅，"legacy"❌ - 大小写敏感：Linux/macOS 下
"Src/"≠"src/"
PSR-4 映射顺序决定谁“赢”，但不可靠
Composer 按 composer.json 中声明顺序注册 PSR-4 规则，后注册的前缀会覆盖前一个——但仅限于“找不到类时继续尝试”。一旦第一个路径下存在匹配文件，后续路径里的同名类就永远不被加载。问题在于：
- 你无法控制哪段代码先触发
new或use，所以实际加载哪个版本是随机的 - 如果某处手动
require 'vendor/a/src/Helper.php'，而 autoload 又试图加载vendor/b/src/Helper.php，就会立刻崩 - CLI 脚本和 Web 请求的加载顺序可能不同，导致“有时报错、有时不报”这种最头疼的情况
真正能落地的解法只有两个
改源码或加代理，别信“alias”或“自动隔离”：
- 上游可维护时：直接修改冲突包的
composer.json，把"App\": "src/"改成唯一前缀，如"VendorA\App\": "src/"，并同步改类文件顶部的namespace - 上游不可控时：复制冲突文件到自己项目（如
src/VendorA/Helper.php），改命名空间为VendorA，再在自己项目的composer.json中加"VendorA\": "src/VendorA/" - 别碰
class_alias()当主力方案——它要求目标类已加载，且不能重复执行；更适合临时兼容老 SDK，而非解决 autoload 劫持
最常被忽略的点：命名空间重叠往往不是配置失误，而是架构信号——说明项目里混用了未收敛的私有包、测试类泄漏进生产 autoload、或强行复用非标准命名空间。比起修配置，先问一句：这个类真该暴露在全局 PSR-4 下吗？
