PHP 修改自动加载映射后为什么必须重新 dump-autoload

把 composer.json 里的 PSR-4 目录从 app/ 改成 src/，却仍然遇到 Class not found，通常不是 PHP 忽略了配置，而是 Composer 生成的自动加载文件还停留在旧映射。修改自动加载映射后，先在项目根目录执行 composer dump-autoload，再检查命名空间、目录和文件名大小写；不要一上来删除整个 vendor。

Composer 读取的是已生成的自动加载入口。改动 autoload.psr-4 后重新 dump，才能把新映射写入 vendor/composer；如果只是向现有 PSR-4 目录新增类，普通开发模式通常可以直接发现，但 classmap 或 authoritative classmap 场景仍要重建。

为什么改了映射却还是 Class not found

Composer 的 PSR-4 配置是“命名空间前缀到相对目录”的映射。例如 Demo\ 指向 src/ 时，Demo\DemoService 对应的文件应是 src/DemoService.php。Composer 会在安装或更新阶段把这些引用合并到 vendor/composer/autoload_psr4.php，vendor/autoload.php 再把相关加载器注册到 PHP 运行时。

因此，composer.json 改了并不等于 vendor/composer/autoload_psr4.php 已经改了。旧的 PHP-FPM worker、队列常驻进程还可能继续持有旧代码路径；这时“我明明改了配置”的现象其实混合了两个层次：磁盘上的生成文件是否更新，以及运行进程是否重新加载。

先按四个位置核对 PSR-4 映射

不要只盯着命名空间。下面这组对应关系更适合排查：

一个最小的 composer.json 片段如下。JSON 必须保持合法，所以解释放在代码块外：Demo\ 是命名空间前缀，src/ 是相对项目根目录的目录。

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

对应的 PHP 检查代码应该和应用使用同一份自动加载入口：

这里的 false 只说明当前入口无法解析这个类，不等于类文件内容一定有错。先继续看生成文件和当前工作目录。

dump-autoload 到底更新了什么

composer dump-autoload 的作用是重建自动加载器，不需要重新执行依赖解析。修改 autoload、切换 PSR-4 目录、使用 classmap，或者新增需要被扫描的类时，它比删除 vendor 更精准。

# 在包含 composer.json 的项目根目录重建自动加载器。
composer dump-autoload

# 生产部署时把 PSR-4/PSR-0 规则转换为 classmap。
composer dump-autoload -o

# 优化时同时报告项目自身的 PSR-4/PSR-0 映射错误。
composer dump-autoload -o --strict-psr

开发阶段先用普通命令，便于新增类后快速发现。生产构建可用 -o，因为部署后类文件通常不会随机出现。--classmap-authoritative 会让未出现在 classmap 的类直接视为不存在，运行时生成类或依赖这类机制的项目要谨慎使用；它不是“更强的 dump”，而是更严格的运行时边界。

重建后仍报错时的最小收尾清单

1. 确认命令在含目标 composer.json 的项目根目录执行，必要时用 composer dump-autoload -d /path/to/project 明确工作目录。
2. 打开实际被引入的 vendor/autoload.php，确认不是测试目录、旧发布目录或另一份依赖目录。
3. 逐字比较命名空间、类名、文件名和大小写；Linux 文件系统不会替你纠正大小写。
4. 如果命令行检查为真而 PHP-FPM 或队列仍为假，重载对应常驻进程，让它重新读取发布目录。
5. 若启用了 -a，先用普通 dump 验证，再检查目标类是否确实出现在 classmap 允许的范围内。

判断是否需要更新依赖，可以把问题拆开：只改自动加载映射，用 dump-autoload；改了依赖版本约束，才考虑 update；安装已有锁定版本则使用 install。这三者混用，往往会把一个路径问题扩大成依赖变更。

常见问题

新增一个已有 PSR-4 目录下的类，也必须 dump-autoload 吗？

普通 PSR-4 开发模式通常会按规则查找新文件，不一定需要；如果启用了优化 classmap、authoritative classmap，或修改的是映射本身，就应重新 dump。

dump-autoload 会重新安装全部依赖吗？

不会。它主要重建自动加载器，不负责重新解析并安装依赖版本。

为什么本地正常，部署后却找不到类？

常见差异是部署使用了 classmap、路径大小写不同、发布目录中没有重新生成 vendor，或常驻进程仍指向旧版本目录。