PSR-4配置必须严格匹配：命名空间前缀以双反斜杠结尾（如"App"），路径为相对目录且不带末尾斜杠（如"src"），修改后须执行composer dump-autoload -o生效，错一处即Class not found。
psr-4 配置写错一个字符就找不到类
PSR-4 不是“大概对就行”，它要求命名空间前缀必须以 \ 结尾，路径值必须是相对于 composer.json 的目录，且不带末尾斜杠。比如 "App\": "src" ✅，写成 "App": "src" 或 "App\": "src/" ❌，都会静默失效。
常见错误现象：Class 'AppUserRepository' not found，但文件明明在 src/User/Repository.php 里。
-
namespace声明必须与前缀完全一致：文件中写namespace AppUserRepository;，不能漏掉App\或多写; - 类名必须与文件名严格一致（大小写敏感）：
Repository.php里只能有class Repository，不能是repository或RepositoryClass - 路径分隔符统一用
/，即使在 Windows 上——Composer 内部会自动转换，别手动写\ - 多个 PSR-4 映射共存时，更具体的前缀要写在前面（如
"App\Http\": "src/Http/"应在"App\": "src/"之前），否则宽泛规则先命中，后续规则被跳过
classmap 和 files 各自该用在什么场景
classmap 适合无命名空间的老代码、扁平结构的工具类或第三方遗留库；files 只用于全局函数、常量定义或一次性初始化脚本，它不参与类加载流程，只是无条件 include_once。
常见错误现象：把 helpers.php 放进 files 却写成相对路径 "helpers.php"，实际应写为 "src/helpers.php"（相对于 composer.json）。
-
classmap必须手动执行composer dump-autoload -o才生成映射表，增删文件后不重跑就会加载失败 -
files数组内文件按声明顺序执行，前面的可以被后面的覆盖（如函数重定义），但一旦某个文件解析出错（ParseError），整个 autoload 初始化失败 -
files中的代码在每次请求启动时都执行，不适合放耗时逻辑；classmap查找快，但体积大、更新滞后，上线环境才建议加-o
autoload-dev 配置为什么在 CI 环境里失效
autoload-dev 下的映射（如 "Tests": "tests/"）只在 require-dev 包已安装、且未使用 --no-dev 时才生效。CI 脚本若默认加了 --no-dev，测试类就彻底不可见。
常见错误现象：Class 'TestsTestCase' not found，本地能跑，CI 直接报错。
- 确认 CI 命令是否含
--no-dev；若需加载测试类，去掉该参数，或改用composer install --no-interaction - 测试类不应塞进主
autoload，否则上线包会多带测试代码，增大部署体积 - 如果测试类依赖
src/下的类，确保主autoload已正确定义，autoload-dev只管自己那块路径
改完 composer.json 为什么还是 class_exists 返回 false
最常被忽略的是：没在 composer.json 所在目录执行 composer dump-autoload，或当前项目启用了 Composer 插件导致缓存干扰。
常见错误现象：修改了 psr-4 映射，运行 composer dump-autoload 后 class_exists('AppService') 仍返回 false。
- 检查执行命令的当前工作目录是否就是
composer.json所在目录（不是子目录如src/） - 临时加
--no-plugins参数重试：composer dump-autoload --no-plugins，排除插件缓存干扰 - 确认没有残留的
__autoload函数或错误调用spl_autoload_unregister，它们会直接覆盖 Composer 的加载器 - 验证是否真正引入了
vendor/autoload.php：它必须在任何类实例化之前require，且不能被其他require语句挡在后面
真正麻烦的不是配置语法，而是路径、命名空间、文件系统大小写、执行上下文这四者的耦合。Linux 部署时一个字母大小写不对，class_exists 就返回 false，而开发机上完全没提示。
