class_exists()返回false说明类未被autoloader注册，非命名冲突；应先验证vendor/autoload.php是否正确引入、检查autoload_psr4.php映射、运行composer dump-autoload -v确认扫描路径，并清理autoload_*.php缓存。
class_exists() 返回 false？先确认 autoload 根本没加载，不是“冲突”
报 Class not found 或 Cannot declare class 时，90% 的情况根本不是命名冲突，而是类压根没被 autoload 注册进来。比如漏了 require 'vendor/autoload.php'，或者 Web 入口用 $_SERVER['DOCUMENT_ROOT'] 拼错路径，实际加载的是旧缓存的 autoload.php。
验证方式极简：在出错脚本开头加一行 var_dump(class_exists('YourClass'));。返回 false 就说明 autoloader 压根不认识这个类——别急着改命名空间，先查加载链。
- 检查
vendor/composer/autoload_psr4.php，搜索你的类名关键词（如UserRepository），看是否出现在两条及以上映射里；只有真出现多次，才是重名实锤 - 运行
composer dump-autoload -v，观察终端输出中是否扫到了你预期的类路径 - 删掉整个
vendor/composer/autoload_*.php，再执行一次dump-autoload，排除旧缓存干扰
PSR-4 映射重叠时谁生效？最长前缀优先，不是配置顺序
Composer 不按 composer.json 里 psr-4 数组的书写顺序决定加载优先级。它只认“最长前缀匹配”：比如你同时配了 "App\": "src/" 和 "App\Helper\": "vendor/pkg/src/Helper/"，那么 new AppHelperUserService() 一定走后者；但 new AppUserService() 仍走前者——后者根本不会参与匹配。
更危险的是写两个宽泛前缀，比如都用了 "App\": "src/"，这时 Composer 会按 autoload_psr4.php 里的数组顺序注册，后注册的映射会覆盖前注册的键，但 PHP 加载时谁先 new 谁生效，行为不可控。
- Composer 2.2+ 已禁用同一命名空间配多个路径（如
"App\": ["src/", "legacy/"]），会直接报错 -
prepend: true对autoload无效，它只影响repositories - 真正让自定义路径优先的唯一可靠方式是运行时调用
$loader->prependPsr4('MyOverride\', __DIR__ . '/overrides/')，且必须在require 'vendor/autoload.php'之后立即执行
classmap 和 PSR-4 同时存在，谁先抢到类？classmap 总是赢
classmap 是 autoload 流程的第一道关卡。只要你在 composer.json 的 classmap 字段里写了 "src/Helper.php"，那么 new Helper() 就永远走 classmap，完全跳过 PSR-4 推导；而 new AppHelper() 还是走 PSR-4——它们不打架，但容易让你误判来源。
排查关键点：
- 运行
composer dump-autoload -v，看输出里是否真扫到了你认为该进classmap的文件 - 检查
exclude-from-classmap写法：只认完整路径（"src/Deprecated/Helper.php"）或目录（"legacy/"），"Helper"或"src/Deprecated/*"全部静默忽略 -
exclude-from-classmap对 PSR-4 完全无效，它只管classmap
fork 包改名后仍冲突？name 字段和 autoload 必须同步改
报错 Package monolog/monolog is already registered 是注册阶段就失败，根本没机会走到自动加载。根源是 fork 后没改 composer.json 里的 name 字段，导致两个包共用同一键（如都叫 monolog/monolog）。
修复必须三步同步：
- 改
name：比如从monolog/monolog改成yourname/monolog - 同步更新
autoload.psr-4映射路径，确保新命名空间指向新物理路径（如"YourName\Monolog\": "src/"） - 主项目
composer.json的require行要指向新名字："yourname/monolog": "dev-main"
私有镜像里多个环境（dev/staging）若共用同一 name，也会中招——名字必须全局唯一，不能靠分支区分。
