composer不自动处理类名冲突，仅按配置注册加载规则；同名类会导致php致命错误。需先验证autoload是否生效，再检查psr-4前缀、classmap优先级及离线环境配置。

Composer 自动加载器冲突不是“会不会发生”的问题，而是“什么时候暴露”的问题——只要两个包注册了相同类名或重叠命名空间，require vendor/autoload.php之后第一次 new 那个类，PHP 就会直接报 Fatal error: Cannot declare class Xxx，不给任何缓冲机会。

为什么 require vendor/autoload.php 后还是 Class not found？

这不是 autoload 没加载，而是它加载了“错误的” autoload —— 常见于多入口、多 autoloader 并存场景：

• 你在 index.php 里 require 'vendor/autoload.php'，但在 404.php 或 cli/backup.php 里又 require 'lib/autoload.php'（自定义加载器），后者没声明 Twig\ 或 GuzzleHttp\，一进错误流程就崩
• vendor/autoload.php 被符号链接或挂载到非标准路径（如 Docker 中 /app → /host/project），导致里面硬编码的 __DIR__ 指向空目录，PSR-4 映射全部失效
• 你手动 include 过某个 Helper.php，而 Composer 后续又尝试加载同名类，PHP 报的是 “Cannot redeclare”，但你以为是“找不到”

验证方式：在出错脚本开头加一行 var_dump(class_exists('Twig\Loader\FilesystemLoader'));，false 就说明 autoload 根本没走对路。

PSR-4 命名空间撞车的快速定位与隔离

冲突最常发生在宽泛前缀上，比如两个包都配了 "": "src/" 或 "App\": "src/"。Composer 不做去重，只按 composer.json 顺序注册，后注册的覆盖前注册的——但 PHP 加载时谁先被 new 谁生效，行为不可控。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 用 composer dump-autoload -v 看输出里是否重复出现同一命名空间（例如两行都含 App\ => src/）
• 检查 vendor/composer/autoload_psr4.php，搜索类名关键词，确认它映射到了哪个路径；如果一个类出现在两个路径下，就是撞车实锤
• 不要试图在 autoload 里加别名字段（如 "MyApp\AppHelper": "vendor/a/Helper.php"）——Composer 不支持运行时类重命名
• 可行解法只有两个：改源码命名空间（上游可维护时），或用代理类封装（推荐）。例如把 vendor/a/pkg/src/Helper.php 复制进 src/VendorA/Helper.php，顶部改成 namespace VendorA;，再在 composer.json 中加 "VendorA\": "src/VendorA/"

classmap 和 PSR-4 混用时谁优先？

classmap 是自动加载流程的第一道关卡，命中即返回路径，完全跳过 PSR-4 推导。这点必须清楚，否则你会误判冲突来源。

• 如果你在 composer.json 的 classmap 里写了 "src/Cache.php"，那么 new Cache() 就走 classmap；但 new App\Cache() 仍走 PSR-4 —— 类名不匹配，不会混
• PSR-4 映射末尾必须带反斜杠："App\": "src/" ✅，"App\": "src" ❌（后者会让 App\Foo 去找 src/App/Foo.php）
• classmap 路径写相对路径即可，如 "lib/"，不能写 "./lib/" 或绝对路径；执行 composer dump-autoload -o 后，classmap 生成完整列表，但 PSR-4 仍保留 fallback 行为（即文件不存在时继续往下找）
• 若想临时屏蔽某个冲突类，可用 "exclude-from-classmap": ["vendor/bad/pkg/src/ConflictClass.php"] —— 注意：这只对 classmap 有效，对 PSR-4 无效

离线环境下的 autoload 冲突修复要点

离线时没有网络回退机制，composer install 可能跳过 autoload 重建，旧映射残留是常态。此时不能依赖“重装”，得靠手动干预。

• 强制重建 autoload：composer dump-autoload --optimize（别加 --classmap-authoritative，它会删掉 PSR-4 fallback，离线时容易让动态生成的类加载失败）
• 检查 vendor/composer/autoload_static.php 文件修改时间，必须和 composer.json 修改时间一致；不一致说明 dump-autoload 没真正生效
• OPcache 会缓存这个静态文件的字节码，重启 PHP-FPM 或执行 php -r "opcache_reset();" 是必要步骤
• 如果冲突来自多个包共用同一类名且无法改源码，files 加载方式最可靠："autoload": {"files": ["vendor/good/pkg/helpers.php"]}，绕过所有映射逻辑，直击文件

最易被忽略的一点：vendor/autoload.php 里有大量硬编码路径，一旦项目移动、挂载或软链，它就失效——这不是配置问题，是设计使然。所以别共享 vendor 目录，也别用 rsync 复制它。该重装就重装，该重建就重建。