Composer不解决类名冲突，只注册加载路径；同名类会导致PHP致命错误。确认是否真冲突需先验证autoload是否生效，检查vendor/autoload.php引入、路径、dump-autoload输出及composer.json配置有效性。
Composer 不会自动注入类，也不会“解决”类名冲突——它只按配置注册加载路径。一旦两个包都声明了同名类（比如 App\Helper），PHP 在第二次尝试加载时直接抛出 Fatal error: Cannot declare class AppHelper，不给重试机会，也不报 warning。
怎么确认是真冲突，还是 autoload 根本没生效
很多“类冲突”其实是 autoloader 压根没加载成功，先排除这个低级但高频的问题：
- 检查入口文件是否真的
require了vendor/autoload.php，CLI 脚本里漏写这行很常见 - 用
file_exists(__DIR__ . '/vendor/autoload.php')手动验证路径，尤其注意 Web 环境下$_SERVER['DOCUMENT_ROOT']和脚本实际位置可能不一致 - 运行
composer dump-autoload -v，看输出里有没有扫到你的命名空间和文件；如果压根没出现，说明composer.json的autoload配置无效（比如缩进错、逗号漏、PSR-4 末尾少反斜杠） - 删掉
vendor/composer/autoload_*.php后再跑dump-autoload，避免旧缓存干扰
PSR-4 命名空间撞车的典型表现和解法
最常见冲突来源：两个包都用了宽泛前缀，比如都配了 "App": "src/" 或 "": "src/"。Composer 会把它们全注册进 autoloader，运行即崩。
- 检查所有依赖包的
composer.json，重点看autoload和autoload-dev字段是否用了全局映射（如""）或过宽前缀（如"App\"） - 你自己项目中，绝不要把多个第三方包的源码目录塞进同一个命名空间下——哪怕只是放
Helper.php - 优先推动包作者收紧前缀，例如从
"App\": "src/"改成"VendorName\Package\": "src/" - 若无法推动上游修改，可在你项目的
composer.json中用exclude-from-classmap主动屏蔽冲突文件（注意：这只对classmap有效，对 PSR-4 无效）
classmap 和 PSR-4 混用时谁说了算
classmap 查表是 autoload 流程的第一步，一旦命中就直接返回路径，完全跳过 PSR-4 推导。这意味着：
- 如果你在
classmap里手动加了"src/Helper.php"，那么new Helper()就走classmap；而new AppHelper()仍走 PSR-4 —— 类名不匹配，不会混 - PSR-4 映射必须以反斜杠结尾：
"App\": "src/"✅，"App\": "src"❌（后者会导致类名解析多一层） -
classmap路径写相对路径（如"lib/"），不能写"./lib/"或绝对路径 - 执行
composer dump-autoload -o后，classmap生成完整列表，但 PSR-4 映射仍保留 fallback 行为
用代理类封装冲突类（推荐用于生产环境）
不碰原包代码、不改命名空间、兼容性最强的方式是写一层薄代理。比如两个包都提供 CacheInterface，但实现互不兼容：
- 在项目
src/Adapter/下新建VendorACacheAdapter.php，内部use并包装vendor-a/package的实现 - 同理建
VendorBCacheAdapter.php包装另一个 - 业务代码只依赖你自己的
CacheInterface和这两个适配器，彻底隔离外部变更 - 这种方式不依赖 Composer autoload 配置，也不受
exclude-from-classmap影响，部署稳定
真正难处理的不是报错本身，而是两个包都声称自己“只是工具类”，却悄悄把 App\ 这种命名空间写死在 composer.json 里——这种设计缺陷往往要等到上线后才暴露，且排查成本远高于提前约定规范。
