Composer 不会自动解决类名冲突，同名类会导致 PHP 直接报 Fatal error；需先确认 autoload 是否生效，再排查 PSR-4 前缀过宽、classmap 与 PSR-4 优先级、--classmap-authoritative 配置错误等问题。
Composer 不会自动解决类名冲突，只要两个包声明了同名类，PHP 就会在第二次加载时直接报 Fatal error: Cannot declare class——没警告、不重试、立刻崩。
怎么确认是真冲突，还是 autoload 根本没生效
很多“冲突”其实是 autoload 没跑起来，先排除这个高频低级问题：
- 检查入口文件是否真的
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/"改成"VendorNamePackage\": "src/" - 若无法推动上游修改，可在你项目的
composer.json中用exclude-from-classmap主动屏蔽冲突文件（注意：这只对classmap有效，对 PSR-4 无效）
classmap 和 PSR-4 混用时谁说了算
classmap 查表是 autoload 流程的第一步，一旦命中就直接返回路径，完全跳过 PSR-4 推导。
立即学习“PHP免费学习笔记（深入）”；
- 如果你在
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 行为
生产环境 autoload 还慢？别只盯着 dump-autoload -o
composer dump-autoload -o 在绝大多数项目里是无效的，它不会重建 vendor/composer/autoload_classmap.php，只是“假装优化”。真正起效的是：
-
composer install --no-dev --optimize-autoloader（部署 CI/CD 中必须写死） -
--classmap-authoritative确实快，但它不是“更快的 autoload”，而是“更严格的 autoload”：类不在classmap里就直接抛Class not found，不尝试拼路径、不file_exists()、不遍历目录 - 开了
--classmap-authoritative却报错，大概率是新增类没被扫进classmap：比如命名空间写成namespace AppConsoleCommands;，但 PSR-4 前缀配的是"App\": "app/"（缺反斜杠），导致扫描失败 -
files类型加载的全局函数（如"files": ["app/Helpers/functions.php"]）不会进classmap，开了-a后它们依然能加载，但别误以为所有 autoload 都走classmap
复杂点在于：autoload 冲突往往不是单点问题，而是配置、路径、命名空间、加载顺序、甚至框架自加载器（如 ThinkPHP 的 Loader::register()）层层叠加的结果。最容易被忽略的是——你以为改了 composer.json 就生效了，其实没跑 install 或漏了 --no-dev，classmap 根本没更新。
