Composer不自动处理类名冲突，仅按配置注册加载规则；同名类会导致PHP致命错误。需先验证autoload是否生效，再检查PSR-4前缀、classmap优先级及离线环境配置。
自动加载冲突不是 Composer “没配好”，而是多个命名空间映射到了同一类名，PHP 直接 Fatal error —— 没有重试，不给提示，崩得干脆。
Class not found 却有文件？先确认 autoload.php 是否真被 require
很多报错看起来像加载失败，实际是入口根本没走 Composer 自动加载流程。
- 检查脚本第一行是否写了
require __DIR__ . '/vendor/autoload.php';，CLI 脚本里漏掉这句太常见 - Web 环境下用
file_exists(__DIR__ . '/vendor/autoload.php')手动验证路径，$_SERVER['DOCUMENT_ROOT']和实际脚本位置经常不一致 - 运行
composer dump-autoload -v，看输出里有没有扫到你的命名空间；如果完全没出现，说明composer.json的autoload字段配置无效（比如 JSON 逗号漏了、缩进错、PSR-4 前缀末尾少了反斜杠） - 删掉
vendor/composer/autoload_*.php再跑一次dump-autoload，避免旧缓存干扰
PSR-4 命名空间撞车：两个包都声明了 App\ 怎么办
这是最典型的加载冲突来源。Composer 会把所有 PSR-4 映射全注册进去，一旦两个包都用了 "App\": "src/"，new AppHelper() 就会随机加载其中一个，第二次加载直接报 Fatal error: Cannot declare class AppHelper。
- 检查你项目和所有依赖包的
composer.json，重点看autoload和autoload-dev字段是否用了宽泛前缀，比如""或"App\": "src/" - 你自己项目中，绝不要把多个第三方包的源码目录塞进同一个命名空间下——哪怕只是放一个
Helper.php - 优先推动包作者收紧前缀，例如从
"App\": "src/"改成"VendorName\Package\": "src/" - 若无法推动上游，可在你项目的
composer.json中用exclude-from-classmap主动屏蔽冲突文件（注意：这只对 classmap 有效，对 PSR-4 无效）
离线环境 Class not found？autoload 映射可能根本没更新
离线时 composer install 可能跳过 autoload 重建步骤，导致 vendor/autoload.php 里没注册新类或路径变更后的类。
- 手动触发重建：
composer dump-autoload --optimize（别加--classmap-authoritative，它会删掉 PSR-4 回退逻辑，离线时反而更脆） - 确认
composer.json中的autoload路径是真实存在的本地路径（如"src/": ["src/"]），离线时不能依赖远程或未提交的目录 - 检查
vendor/composer/autoload_static.php文件修改时间，和composer.json修改时间对比；不一致说明dump-autoload没生效 - OPcache 可能缓存了旧的 autoload_static，重启 PHP-FPM（不是 reload），或临时加
opcache.validate_timestamps=1到php.ini
多个 autoloader 共存时谁说了算
当项目里混用了 Composer autoload、手动 require、ThinkPHP 自带加载器，甚至全局 Composer 工具，类加载顺序就变成黑箱。
- classmap 是 autoload 流程的第一步，一旦命中就直接返回路径，完全跳过 PSR-4 推导
- PSR-4 映射必须以反斜杠结尾：
"App\": "src/"✅，"App\": "src"❌（后者会导致类名解析多一层） - 避免手动
include或require第三方类库，尤其不要在vendor/下再手动引——Composer 已经管了，重复引就是给自己埋雷 - ThinkPHP 6 应使用标准 Composer 结构，自定义模块也应统一注册到
autoload，而不是靠extend/目录 + 手动加载
真正麻烦的从来不是“怎么写配置”，而是当多个包都悄悄注册了 App\，而你只在报错堆栈里看到一行 Fatal error —— 那时候就得翻遍所有 composer.json 的 autoload 段，一个一个比对前缀。
