autoload 配置只能写在项目根目录的 composer.json 文件中，通过 autoload 或 autoload-dev 字段声明；修改后必须运行 composer dump-autoload 或 composer install 才生效。
autoload 配置写在哪？不是 composer.json 就无效
自定义 autoload 的入口只有 composer.json 里的 autoload 或 autoload-dev 字段，其他地方（比如代码里手动 require、.env 文件、脚本钩子）改了都不触发 Composer 的自动加载机制。
常见错误是把映射逻辑写在 index.php 里用 set_include_path 或 spl_autoload_register 手动注册——这会绕过 Composer，导致 vendor/autoload.php 加载后类仍找不到，或与 Composer 的 PSR-4/Classmap 冲突。
-
composer.json必须在项目根目录（即运行composer install的当前目录），否则 Composer 直接报错Could not find a composer.json file - 如果项目实际源码不在
src/或lib/这类标准路径，就得在autoload里显式声明真实路径，比如"App\": "app/" - 修改完
composer.json后必须运行composer dump-autoload（开发时）或composer install（部署时），否则新映射不会写入vendor/composer/autoload_*.php
PSR-4 和 classmap 混用时谁优先？
PSR-4 是前缀匹配 + 目录映射，classmap 是扫描后硬编码的全量类名到文件路径表。两者共存时，Composer 查找类的顺序是：先查 PSR-4，没命中再查 classmap —— 但一旦 PSR-4 规则“看似能匹配”，就会尝试去对应目录找文件，哪怕该文件实际不存在，也不会 fallback 到 classmap。
典型翻车场景：你写了 "MyLib": "legacy/"，但 legacy/ 下混着 PHP 文件和非 PHP 文件（如 .inc 或模板），而你想让其中几个老类走 classmap。这时候必须把它们单独拎出来，用 classmap 指向具体文件或子目录：
"autoload": {
"psr-4": {
"MyLib\": "legacy/src/"
},
"classmap": ["legacy/old_lib/", "legacy/Utils.php"]
}
- PSR-4 要求命名空间前缀必须以
\结尾；漏掉会解析失败，且不报错，只是映射失效 - classmap 扫描结果是一次性生成的，删了文件但没重跑
composer dump-autoload，旧路径仍留在 autoload_classmap.php 中，导致Class not found变成require(): failed to open stream - 如果 legacy 目录结构极深或文件极多，classmap 会导致
vendor/autoload.php加载变慢，优先用 PSR-4 显式声明子目录
vendor/autoload.php 被 include 多次会怎样？
不会报错，但会重复注册 autoloader 函数，造成性能损耗，且可能干扰其他依赖的 autoloader（比如 Laravel 的 ClassLoader 或 PHPUnit 的测试加载器）。
根本原因常是：框架或脚本里写了 require __DIR__.'/vendor/autoload.php';，而你又在命令行执行 php -d auto_prepend_file=vendor/autoload.php script.php —— 这种双重加载在 CI 环境或调试时特别隐蔽。
- 检查是否用了
auto_prepend_file、auto_append_file这类 php.ini 设置 - 用
get_included_files()在关键位置打印，确认vendor/autoload.php是否出现多次 - 所有项目入口（
index.php、cli.php、测试启动脚本）只应有一处require，且放在最顶部、无条件执行
为什么 dump-autoload 后类还是找不到？重点查这三处
不是配置写错了，就是路径没对上。Composer 不校验目录是否存在，也不检查文件是否真有对应类 —— 它只按规则拼路径，然后由 PHP 的 require 去读文件，失败就抛 Class not found。
- 用
composer show --platform确认当前 PHP 版本满足composer.json的require约束，低版本 PHP 无法加载高版本语法的类文件 - 检查路径是否含大小写错误：
App/Controller和app/Controller在 Linux 下是不同路径，但 Windows 可能不报错，导致本地正常、线上挂掉 - 运行
composer dump-autoload -v，看输出里有没有类似Warning: Class MyLibOldClass was not found in file ...的提示，它会暴露 PSR-4 映射后实际拼出的路径
最麻烦的是符号链接（symlink）路径：Composer 默认不跟随 symlink，除非你在 composer.json 里加 "optimize-autoloader": true 并配合 --apcu 或确保 realpath() 能正确解析。这种问题往往只在容器或部署环境暴露。
