PSR-4自动加载必须三步齐备：正确配置composer.json中顶层autoload字段的命名空间与路径映射（如"App\": "src/"）、类文件路径严格匹配命名空间层级（App\Http\Controllers\HomeController→src/Http/Controllers/HomeController.php）、修改后运行composer dump-autoload生成autoload_psr4.php。
PSR-4 自动加载不会“自动生效”，必须手动在 composer.json 中写对映射、路径和命名空间，再运行 composer dump-autoload，三者缺一不可。
composer.json 的 autoload 字段必须是顶层键
它不能嵌在 require、config 或 scripts 里，否则 Composer 完全忽略。常见静默失效就是拼错键名，比如写成 auto-load 或 autoloader。
-
autoload必须和name、require并列，是 JSON 的一级字段 - 路径值如
"src/"是相对于composer.json所在目录的子路径，不支持../src或绝对路径 - 命名空间键必须以双反斜杠结尾：
"App\"✅，"App"❌，"\App\"❌（开头反斜杠非法）
App\Http\Controllers\HomeController 对应什么路径？
Composer 不扫描文件，只做字符串拼接：剥离前缀 App\ 后，剩余部分 Http\Controllers\HomeController 被转为路径 Http/Controllers/HomeController.php，再拼上配置里的根目录（如 src/），最终加载 src/Http/Controllers/HomeController.php。
- 文件必须真实存在，且大小写完全一致：
src/Http/Controllers/≠src/http/controllers/ - 类文件名必须等于类名：
class HomeController→ 文件必须叫HomeController.php - PHP 文件内
namespace声明不能有空格或 tab 缩进：namespace AppHttpControllers;✅，namespace AppHttpControllers ;❌
为什么 vendor/autoload.php 引入了还是 Class not found？
因为 vendor/autoload.php 只是入口，真正起作用的是 vendor/composer/autoload_psr4.php —— 这个文件不会自动更新，必须靠 composer dump-autoload 重写。
- 改完
composer.json后没运行命令，映射就不存在于 autoload_psr4.php 中 - 运行
composer dump-autoload -o会生成优化版 classmap，跳过运行时路径检查，反而掩盖路径错误，调试阶段建议先用不带-o的版本 - 可临时加一句
var_dump(include 'vendor/composer/autoload_psr4.php');直接看数组里有没有你配的键值对 - Docker 环境下要注意：在容器 A 里执行了
dump-autoload，但应用跑在容器 B 里，vendor/没同步也会失败
多个 PSR-4 映射共存要注意什么？
可以并列定义，但 Composer 匹配时按“最长前缀优先”，不是 JSON 键顺序。比如同时配了 "App\" 和 "App\Http\"，那么 App\Http\Controllers\Home 会命中后者；但如果把 "App\" 写在前面且没配更具体的，就可能被宽泛前缀截胡。
- 测试类务必单独配在
autoload-dev下，例如"Tests\": "tests/"，避免混进生产环境 - 不要用空字符串
""或单反斜杠"\"作命名空间前缀，Composer 7+ 会直接拒绝安装 - 同一目录不能强行对应两个不同前缀（如
"App\"和"Domain\"都指向src/），容易引发类名冲突或加载错位
最常被忽略的一点：Linux/macOS 下文件系统区分大小写，而 Windows 不区分——开发时看似正常，部署到服务器立刻报错。别依赖 IDE 自动重命名，手动确认每个目录名、文件名、命名空间字母大小写是否完全一致。
