PSR-4自动加载需三者严丝合缝：composer.json中顶层autoload字段的正确映射、类文件路径与命名空间严格一致、手动执行composer dump-autoload更新autoload_ps4.php，缺一即Class not found。

PSR-4 自动加载不是“配完就能用”的功能，它依赖三者严丝合缝：composer.json 中的映射声明、类文件的物理路径与命名空间声明、以及手动触发的 composer dump-autoload。缺一不可，错一个字符就 Class not found。

composer.json 的 autoload 字段必须是顶层键，且格式不能有毫厘之差

Composer 完全忽略嵌套在 require、config 或 scripts 下的 autoload。它必须和 name、require 并列，是 JSON 的一级字段。

• "App": "src/" ✅ —— 命名空间键末尾是双反斜杠（JSON 中表示字面量 ），路径以 / 结尾
• "App": "src/" ❌ —— 少一个 ，匹配逻辑失效，Composer 静默跳过该条目
• "App": "src" ❌ —— 路径没结尾 /，可能和同名文件冲突，部分版本会解析失败
• "App": "./src/" ❌ —— ./ 是非法相对路径，Composer 不支持向上跳转或带前缀的写法
• "autoload" 拼错成 "auto-load" 或 "autoloader" → 配置彻底不生效，无任何提示

PSR-4 映射不是扫描，而是字符串拼接 + 文件存在性检查

Composer 不遍历目录、不读取文件内容，它只做确定性字符串转换：

• 给定类名 AppHttpControllersHomeController
• 剥离前缀 App → 剩余 HttpControllersHomeController
• 将 替换为 / → Http/Controllers/HomeController
• 拼上配置路径 src/ → src/Http/Controllers/HomeController.php
• 最终尝试 include 这个路径（大小写敏感）

所以这些都会失败：

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 文件实际路径是 src/http/controllers/HomeController.php（Linux/macOS 下 ≠ Http/Controllers/）
• 文件名是 homecontroller.php 或 HomeControllerController.php
• 类文件里写的是 namespace AppHttpControllers;，但配置映射是 "App": "src/" → 正确应为 namespace AppHttpControllers; 对应 src/Http/Controllers/HomeController.php，不能多也不能少一级
• 文件内 namespace 行末有空格或 tab：namespace AppHttpControllers; ❌

dump-autoload 不是“可选步骤”，而是强制更新 autoload_psr4.php 的唯一方式

vendor/autoload.php 只是入口引导文件，真正起作用的是 vendor/composer/autoload_psr4.php —— 这个文件不会自动更新，也不会被 composer install 或 update 重新生成（除非锁文件变更）。

• 改了 composer.json 后没跑 composer dump-autoload → autoload_psr4.php 仍是旧内容，new 就报错
• 跑了但用了 --no-dev，而你的类在 autoload-dev 里 → 生产环境找不到
• Docker 环境中在构建阶段跑了 dump，但应用容器挂载的 vendor/ 是另一份 → 映射文件未同步
• CI 部署后 autoload_psr4.php 权限为 600，Web 进程无法读取 → 静默失败
• IDE（如 PHPStorm）缓存了旧的类索引 → 报红但实际运行正常，需手动清 index

为什么 vendor/autoload.php 引入了还是 Class not found？先查这三处

不要急着重写配置，先验证底层是否已对齐：

• 打开 vendor/composer/autoload_psr4.php，确认里面有没有你配的键，比如 'App\' => array($baseDir . '/src')
• 执行 php -r "var_dump(class_exists('AppHttpControllersHomeController'));"，看返回 bool(false) 还是 bool(true)
• 用 realpath() 手动拼出预期路径：php -r "echo realpath('src/Http/Controllers/HomeController.php');"，确认文件真实存在且可读
• 检查当前工作目录是否是项目根目录（尤其 CLI 脚本）——$baseDir 是基于 composer.json 位置计算的，路径错位会导致拼接错误

最常被忽略的点：PSR-4 是大小写敏感的字符串操作，不是模糊查找；autoload_psr4.php 是静态查表，不是运行时逻辑；所有路径都必须相对于 composer.json 所在目录，且不能有任何软链、权限或挂载偏差。