PHP Composer autoload classmap 更新后为何仍找不到类

我遇到过一种很容易误判的 PHP 报错：刚把新类放进 classmap 目录，也执行了 composer dump-autoload，应用仍然提示 “Class not found”。答案通常不是 Composer 没有刷新，而是四个对象没有对齐：扫描目录、文件里的 namespace/class、生成出来的映射，以及正在运行的 PHP 进程实际加载的 vendor/autoload.php。

先在项目根目录重建 autoload，再检查 vendor/composer/autoload_classmap.php 是否出现完整类名，最后用 class_exists($name, true) 区分映射缺失和运行目录错误。

一、先确认 classmap 配置与文件声明

Composer 官方文档说明，classmap 会在 install/update 或 dump-autoload 时扫描配置的目录和文件，并把结果写入 vendor/composer/autoload_classmap.php。因此第一步不是反复重启 PHP，而是沿着一条完整路径核对：composer.json 的路径相对项目根目录，目标文件确实在该目录内，文件声明的完整类名也正是代码里使用的名字。

例如项目结构可以是：

project/
├── composer.json
├── src/Legacy/Invoice.php
└── vendor/

对应的最小配置和类声明如下。示例中的注释只解释检查重点，不代表这段示意代码已经在本机运行。

{
  "autoload": {
    "classmap": ["src/Legacy"]
  }
}

这里最常见的错位有三个：把 src/Legacy 写成相对当前 shell 目录而不是项目根目录；文件实际声明了另一个 namespace；类文件虽然存在，但类名大小写或调用时的反斜杠层级不同。先修正这些，再进入生成步骤。

二、从项目根目录重新生成 autoload

站在包含 composer.json 的项目根目录执行：

# 在项目根目录重建 Composer 自动加载文件，-o 同时生成优化 classmap
composer dump-autoload -o

dump-autoload 的作用是重新生成自动加载器，不会重新解析依赖版本；这正适合“新增类或调整 classmap 后仍找不到”的场景。若你的部署脚本使用了 --no-autoloader，后续安装流程就不会替你生成它，需要在发布阶段显式补上这一步。

如果命令显示完成但问题不变，先不要马上加更多参数。记录这次命令所在目录、使用的 PHP/Composer 可执行文件和 vendor 路径，尤其要排除“本地重建了 A 项目，Web 进程加载 B 项目”的情况。

三、检查生成映射和运行时入口

先做静态确认：在当前项目中搜索完整类名是否出现在 vendor/composer/autoload_classmap.php。映射的键应该是 Demo\Legacy\Invoice，值应该指向项目内的 src/Legacy/Invoice.php。如果键不存在，问题还在配置、扫描范围或生成目录；如果键存在而仍报错，排查方向就转向入口文件和运行环境。

应用入口应加载当前项目的：

CLI、FPM、队列消费者和定时任务可能各自有入口。某个入口修好了，不代表所有进程都已经换到新的 vendor。长驻 worker 还需要按部署方式重启，使它重新 require 新文件；这不是 Composer 的缓存失效，而是进程生命周期没有结束。

四、用 class_exists 区分剩余故障

PHP 手册中，class_exists 的第二个参数决定找不到类时是否尝试自动加载。把自动加载打开和关闭各检查一次，可以快速判断类是否已被加载器找到：

如果第一次是 true，classmap 与入口大概率正常；如果第一次是 false，再看映射文件里有没有这个键。如果映射存在，优先检查加载的 vendor/autoload.php 是否来自另一份发布目录。如果映射不存在，回到第一节检查路径、namespace 和 dump 命令目录。

五、生产环境再看 authoritative 选项

生产环境常用 -o 优化自动加载；而 -a 或 --classmap-authoritative 会进一步规定：classmap 没有的类就视为不存在，不再按 PSR-4 规则继续查找。这能减少文件系统检查，但也意味着运行时才生成的类、部署后未重建的新类会直接失败。

我的做法是把 classmap 重建放进发布流程，并把 -a 留给类集合稳定、每次部署都能完整生成映射的生产包。开发环境新增类时先用普通 dump-autoload，不要用 authoritative 选项掩盖目录或命名空间问题。

相关问答

只执行 composer install 能解决吗？ 如果依赖和自动加载文件确实重新生成，可能可以；但只新增 classmap 类时，直接使用 dump-autoload 更明确，也不会改变锁定的依赖版本。

为什么本地正常、线上仍找不到？ 优先比较线上发布目录里的 autoload_classmap.php、入口文件路径和 worker 启动时间。很多时候本地生成的是新 vendor，线上进程仍指向旧发布目录。

classmap 和 PSR-4 应该选哪个？ 能遵循命名空间到目录规则的新代码优先考虑 PSR-4；遗留目录、非标准文件布局或无法迁移的类再使用 classmap。无论选哪种，部署后的生成物和实际入口都要一致。

这次故障最后可以收敛成一条固定检查链：配置目录 → 文件声明 → dump-autoload 目录 → 生成映射 → 实际入口 → class_exists 结果。只要每一步都指向同一个发布目录，“明明更新过 classmap 仍找不到类”就不会再靠重启和猜参数排查。