Composer autoload 找不到类的典型错误是运行时抛出“Class 'XXX' not found”，主因是PSR-4路径映射不匹配、未执行composer dump-autoload、vendor/autoload.php未正确引入或类名大小写与文件名不一致。
composer autoload 找不到类的典型错误现象
运行时抛出 Fatal error: Class 'XXX' not found 或 Class XXX not found in ...，但文件明明存在、命名也符合 PSR-4 规范。这不是代码写错了，而是 Composer 没把路径映射进自动加载器。
检查 composer.json 的 autoload 配置是否生效
PSR-4 映射必须满足「命名空间前缀」和「物理路径」严格对应，且 composer dump-autoload 必须执行过。常见疏漏：
-
"autoload": { "psr-4": { "App\": "src/" } }中，src/目录下必须有App/子目录，不能直接把类文件放在src/根下 - 修改了
composer.json后没运行composer dump-autoload（开发中建议加-o生成优化版：composer dump-autoload -o） - 用了
classmap但路径写错，或新增文件后没重新 dump（classmap不支持自动发现，必须显式重扫）
vendor/autoload.php 是否被正确引入
这是整个自动加载机制的入口，漏引或引错位置会导致全部失效：
- 确保在项目入口（如
index.php、测试脚本）顶部第一行（无输出前）调用：require __DIR__ . '/vendor/autoload.php'; - 不要用相对路径硬编码，比如
require '../vendor/autoload.php'—— 路径一变就挂 - CLI 环境下注意当前工作目录（
getcwd()），__DIR__才是安全的锚点
类名大小写与文件系统敏感性冲突
Linux/macOS 文件系统区分大小写，Windows 默认不区分 —— 这是跨平台协作中最隐蔽的坑：
- 命名空间写成
AppControllersHomecontroller，但文件叫HomeController.php，在 Windows 下能跑，部署到 Linux 就报错 - PHP 解析类名严格区分大小写，文件名必须完全匹配（包括首字母大写、驼峰连贯性）
- 验证方法：在目标环境执行
ls -l src/Controllers/，看实际文件名拼写
自动加载不是魔法，它靠的是配置、路径、命名三者严丝合缝。少一个 -o、多一个斜杠、差一个大写字母，都可能让类消失。
