PHP Fatal error: Class not found — Composer 自动加载未命中

症状

本篇调试指南针对“PHP Fatal error: Class not found — Composer 自动加载未命中”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• Fatal error: Uncaught Error: Class “App\Service\Mailer” not found
• 本地正常，部署服务器失败
• 新增的类找不到，直到手动改动某处才可用

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

composer dump-autoload -o -vvv

重建类映射会报告扫描了哪些文件，常能暴露路径错误。

步骤 2

composer show -p | grep php && grep -n "psr-4" composer.json

psr-4 块必须把每个命名空间前缀映射到真正存放类文件的目录。

步骤 3

ls -l src/Service/Mailer.php

在 Linux 上文件名大小写与命名空间不一致即失败；需核对确切大小写。

常见诱因（按出现频率排序）：

• PSR-4 命名空间前缀与实际目录路径不匹配
• 优化后的自动加载器在类添加前就已生成
• 文件名大小写与命名空间不符（本地大小写不敏感文件系统掩盖了问题）

根因

Composer 通过生成的自动加载器依据 PSR-4 前缀解析类。当前缀、目录或文件名大小写不完全匹配，或自动加载器陈旧时，类无法定位，PHP 抛致命未找到错误。

修复

让 psr-4 映射与实际目录结构一致、磁盘大小写与命名空间一致，添加类后运行 composer dump-autoload -o，并让部署重新生成自动加载器。

注意：在生产用 –no-dev 执行 dump-autoload -o 会移除仅开发用的类；请核实环境标志。

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

# after adding App\Service\Mailer
composer dump-autoload -o

# production deploy
composer install --no-dev --optimize-autoloader

验证

重新加载页面或运行此前失败的命令，确认类可实例化；检查 dump-autoload 的类映射包含该类。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。