Composer自动加载失败导致类找不到的原因排查

Composer自动加载失败主因是autoload配置错误、vendor/autoload.php未引入、PSR-4路径不匹配或未执行dump-autoload；需确保autoload为顶级字段、命名空间带反斜杠、路径正确、入口文件引入自动加载器，并及时刷新缓存。

autoload 配置没生效：检查 composer.json 的 autoload 字段

遇到Composer自动加载失败，先别急着怀疑自己的代码。很多时候，问题根源在于composer.json里精心配置的路径，压根就没被加载起来。一个典型的陷阱是，把"psr-4"或"classmap"字段放错了位置——比如写在了"require"下面却没做好缩进对齐，或者使用了相对路径却忘了以./开头。

• 首要原则：确保autoload是顶级字段，与require、"name"等字段并列。
• PSR-4映射的命名空间，末尾必须带上反斜杠。例如，"App\": "src/"是正确的，而"App": "src/"就会导致映射失败。
• 如果使用classmap，那么指定的路径必须指向真实存在且包含类定义的PHP文件或目录，同时确保目录可读，并且最关键的一步——执行过composer dump-autoload来生成映射。

vendor/autoload.php 没被引入：确认入口文件是否 require 它

不少开发者执行完composer install后，就以为大功告成，结果一运行脚本就迎面撞上Class not found。其实，根本原因往往很简单：没有在项目的入口PHP文件里显式引入那个至关重要的自动加载器。

• 硬性规定：在使用任何通过Composer安装的包，或者你自己的、遵循PSR标准的类之前，必须先执行require __DIR__ . '/vendor/autoload.php';。
• 路径是关键：这里的vendor/autoload.php路径是相对于当前执行的脚本的位置，而不是相对于项目根目录。在复杂的目录结构中，这一点尤其容易出错。
• 别依赖框架：如果你写的是纯PHP脚本、命令行工具，或者是单元测试的启动文件，都不能指望框架帮你加载，必须手动加上这行代码。

命名空间与文件路径不匹配：PSR-4 规则被违反

PSR-4可不是什么“差不多就行”的模糊匹配，它遵循着严格的映射规则：命名空间的每一级，都必须对应文件系统的一层目录。举个例子，如果你配置了"App\": "src/"，那么当你实例化new App\Http\Controller\HomeController时，Composer就会严格按照规则去寻找src/Http/Controller/HomeController.php这个文件。少一层目录、多一个下划线，或者大小写不一致，都会导致加载失败。

• 文件名必须与类名完全一致，包括大小写。尤其是在Linux服务器上，PHP是严格区分大小写的。
• 类声明里的命名空间，必须与文件的实际路径推导出的命名空间严丝合缝。不要完全依赖IDE的自动生成功能，生成后务必核对。
• 调试小技巧：执行composer dump-autoload -o后，可以临时查看或删除vendor/composer/autoload_psr4.php文件，来验证实际的映射关系是否符合你的预期。

修改后没刷新自动加载缓存：忘记运行 dump-autoload

这是开发中最常见也最令人懊恼的疏忽之一：你修改了composer.json的autoload配置，或者往项目里新增了几个类文件，然后兴冲冲地去运行代码——结果还是报错。原因很简单，Composer不会自动监测这些变动并更新映射表。

• 记住这个命令：composer dump-autoload。任何对自动加载规则的修改，之后都必须运行它来强制重建。
• 关于-o参数：加上它（优化模式）会生成classmap缓存，能提升生产环境的加载性能。但在开发调试阶段，建议先不要使用，以免优化过程掩盖了某些路径配置问题。
• 特殊场景：如果你在安装时使用了composer install --no-autoloader，或者在CI/CD流程中跳过了自动加载器的生成步骤，那么也一定要记得手动补上dump-autoload。

说到底，自动加载失败真正棘手的地方，往往不在于语法或拼写错误，而在于那些关于路径解析的“想当然”。比如，你以为src/是相对于composer.json文件的位置，但实际上它是相对于当前的工作目录；又或者，你改了类的命名空间，却忘了把文件挪到对应的新目录里。这类问题通常不会给出明确的错误提示，只会静默地失败，这才是最考验排查功底的地方。