解决Composer自动加载类找不到（Class not found）的常见排查方法

Composer 找不到类的主因是 autoload 配置未生效，需检查：1. composer.json 中 autoload 路径与命名空间是否匹配；2. 是否执行 composer dump-autoload（推荐加 -o 参数）；3. 类文件是否在声明路径内；4. 命名空间与目录/文件名大小写是否严格一致；5. vendor/autoload.php 是否被正确且优先引入。

检查 composer.json 中的 autoload 配置是否生效

Composer 找不到类，最常见原因是 autoload 没正确声明路径或命名空间。运行 composer dump-autoload 后，它会生成 vendor/autoload.php 和映射文件（如 vendor/composer/autoload_classmap.php），但这个过程只读取 composer.json 里已定义的规则。

常见疏漏包括：

• 用了 "psr-4" 却没让目录结构匹配命名空间层级（例如 "App\\": "src/" 要求 src/Controller/HomeController.php 里必须有 namespace App\Controller;）
• 手动新增了类文件但忘了重新执行 composer dump-autoload（开发中建议加 -o 参数： composer dump-autoload -o 生成优化后的 classmap）
• 误把自定义目录写在 require 而非 autoload 下——require 只控制依赖安装，不参与自动加载

确认类文件是否被 composer dump-autoload 扫描到

Composer 默认不会扫描所有 PHP 文件，只处理 autoload 配置中明确包含的路径。如果类文件放在未声明的目录（比如 lib/ 或 helpers/），即使文件存在、命名空间正确，也会报 Class not found。

验证方式：

• 运行 composer show -s 查看当前 autoload 规则是否包含目标路径
• 打开 vendor/composer/autoload_psr4.php（PSR-4）或 autoload_classmap.php（classmap），搜索你的类名，看是否已注册
• 若使用 "classmap"，需手动添加目录并再次运行 composer dump-autoload；注意 classmap 不支持命名空间推导，只靠文件内 class 声明识别

检查命名空间与文件路径是否严格一致（大小写敏感）

Linux/macOS 系统下，文件系统大小写敏感，而 PSR-4 自动加载器会按命名空间逐级拼接路径。一个字母大小写错误就会导致路径 404，最终触发 Class not found。

Asksia

Asksia AI - 最好的AI老师，可靠的作业助手

下载

典型问题示例：

• 命名空间写成 namespace App\Controllers;，但目录是 src/controllers/（小写 c）→ 应为 src/Controllers/
• 类名是 UserRepository，但文件命名为 userrepository.php → 必须是 UserRepository.php
• 在 Windows 开发、Linux 部署时忽略该差异，本地能跑，上线就报错

建议统一用 ls -la 或 find src -name "*Repository.php" 核对真实文件名。

排除 vendor/autoload.php 未被引入或引入顺序错误

即使 autoload 配置完全正确，如果项目入口没引入 vendor/autoload.php，或者在引入前就 new 了某个类，PHP 仍会直接报错。

关键点：

• 确保 require __DIR__ . '/vendor/autoload.php'; 是第一个执行的语句（尤其注意有没有 include 或 require 其他文件在它之前）
• CLI 脚本和 Web 入口可能用不同引导文件，要分别检查
• 某些框架（如 Laravel）会把 autoload 引入封装在 bootstrap/app.php 之类位置，别只盯着 index.php
• 如果用了 require_once 多次引入 autoload，不会有副作用，但若某处 require 错误路径（比如少个 vendor/），会导致后续自动加载彻底失效

require __DIR__ . '/vendor/autoload.php';

// ✅ 正确：autoload 引入后才实例化
$app = new App\Kernel();

// ❌ 错误：autoload 还没加载就 new，直接 fatal error
// $app = new App\Kernel();
// require __DIR__ . '/vendor/autoload.php';