Composer自动加载未生效,需检查composer.json中autoload配置是否正确定义命名空间与路径映射、末尾反斜杠是否缺失、路径是否相对正确,并执行composer dump-autoload;同时确认vendor/autoload.php被正确引入且类路径严格符合PSR-4规则。

检查 composer.json 中的 autoload 配置是否生效
Composer 找不到类,第一反应不是代码写错了,而是自动加载根本没注册上。重点看 composer.json 里 "autoload" 字段是否正确定义了命名空间与路径映射,且没有拼写错误(比如 "psr-4" 写成 "psr4" 或漏掉冒号)。
常见问题:
-
"psr-4"的键必须以结尾,例如"App\": "src/",写成"App"或"App\"(多一个反斜杠)都会导致匹配失败 - 路径值是相对于
composer.json所在目录的,"src/"实际指向项目根目录下的src/,不是vendor/或其他位置 - 修改后必须运行
composer dump-autoload,仅改配置不执行该命令,变更不会生效
确认类文件路径和命名空间是否严格匹配 PSR-4 规则
PSR-4 不是“尽力而为”的映射,是精确字符串替换。比如配置了 "App\Http\": "src/Http/",那么 AppHttpControllerHomeController 必须落在 src/Http/Controller/HomeController.php —— 少一层目录、多一个下划线、大小写不一致(Linux 下敏感),都会加载失败。
实操建议:
- 用
composer show --platform确认当前环境是否启用了 autoloader(排除 CLI 环境未加载 Composer 自动加载器的情况) - 在终端中手动执行
php -r "var_dump(class_exists('AppHttpControllerHomeController'));",快速验证类是否存在,避免被框架封装层干扰判断 - 检查文件扩展名是否为
.php(不是.inc或.php~等编辑器备份文件)
运行 composer dump-autoload -v 查看详细映射过程
加 -v 参数后,Composer 会输出它实际扫描了哪些目录、注册了多少个命名空间映射。这是最直接的“它到底看见了什么”的证据。
典型输出片段:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
Generated autoload files containing 12 packages
如果这里显示的数字远低于预期(比如只看到 1 个),说明大部分 "autoload" 配置没被读取,大概率是 JSON 格式错误或字段位置不对(比如写在了 "require" 同级但拼错成了 "autoloader")。
注意:composer dump-autoload -o(优化模式)会生成扁平化映射,跳过动态查找,适合生产环境,但调试阶段建议先用普通模式,避免掩盖路径逻辑问题。
排除 vendor/autoload.php 是否被正确引入
即使 Composer 配置全对,如果入口文件(如 index.php 或测试脚本)没 require vendor/autoload.php,或者 require 位置太晚(比如在 new 类之后),照样报 Class not found。
检查点:
- 确认
vendor/autoload.php存在(即已运行过composer install或composer update) - 入口文件第一行(或至少在使用任何依赖类之前)有
require __DIR__ . '/vendor/autoload.php'; - 没有因条件判断(如
if (false) { require ... })导致该行被跳过 - CLI 脚本中没有误用
include替代require,导致静默失败
类加载失败真正卡住的地方,往往不在你写的代码里,而在那行看似不起眼的 require 是否真的执行了、是否路径对得上、是否被覆盖或屏蔽了。

















