PHP Composer PSR-4 类找不到时怎么检查命名空间目录

PHP 项目出现 Class not found 时，最先检查的不是依赖缓存，而是 PSR-4 的四个名字是否一一对应：composer.json 里的命名空间前缀、类声明中的 namespace、目录层级，以及文件名和大小写。确认映射后，在项目根目录运行 composer dump-autoload，再用 class_exists 验证，通常比反复删除 vendor 更快。

实用判断：App\Service\OrderService 在 App\ => src/ 映射下，应该落到项目根目录的 src/Service/OrderService.php，文件里的命名空间也必须是 App\Service。四处有一处不一致，自动加载就可能失败。

先把 PSR-4 命名空间和目录对齐

假设项目根目录下有 src/Service/OrderService.php。composer.json 可以这样声明：

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

对应的 PHP 文件应当写成：

这里的转换规则是：先匹配 App\，把剩余的 Service\OrderService 转成 Service/OrderService.php，再拼到 src/ 后面。前缀末尾的反斜杠不能省略，否则相近的命名空间可能发生错误匹配。

图1：从 App 命名空间前缀到 src/Service/OrderService.php 的静态对应关系。

逐项检查 namespace、目录和文件名

如果映射看起来正确，接着只看目标类本身，不要先怀疑 Composer。最常见的偏差有四种：

• 文件在 src/Service/，却声明成了 namespace App\Services;，多了一个 s。
• 类名是 OrderService，文件却叫 Orderservice.php；在大小写敏感的系统上会失败。
• 把 src/ 写进映射后，又把路径拼成 src/src/Service/OrderService.php。
• 脚本在子目录执行时引入了另一个项目的 vendor/autoload.php。

排查时可以从项目根目录执行：

# 中文注释：确认当前命令所在目录就是 composer.json 所在项目根目录
pwd
ls composer.json src/Service/OrderService.php

# 中文注释：快速读取目标文件的命名空间和类名
sed -n '1,24p' src/Service/OrderService.php

不要只看编辑器能否跳转。编辑器可能使用了自己的索引，而 PHP 运行时只会依据实际加载的 autoload 文件和服务器文件系统判断。

修改后重新生成 Composer 自动加载文件

新增类、调整 PSR-4 映射或移动目录后，在 composer.json 所在目录运行：

# 中文注释：重新生成 vendor/autoload.php 及 Composer 的映射文件
composer dump-autoload

# 中文注释：生产部署可额外生成 class map，提高已知类的查找速度
composer dump-autoload --optimize

开发环境先使用普通模式更容易发现新文件；部署时可以使用 --optimize。如果你启用了只允许 class map 的权威模式，新类没有进入生成结果时会直接表现为找不到，因此不要把优化参数当作修复路径映射错误的替代品。

生成后可以查看 vendor/composer/autoload_psr4.php 是否包含 App\ 到 src/ 的映射。这个文件是 Composer 根据配置生成的结果，适合确认“配置写对了但运行环境读到的是否还是旧结果”。

用 class_exists 做最小闭环验证

最后不要直接启动完整框架。用一个只依赖当前项目 autoload 的命令验证目标类：

输出 bool(true)，说明命名空间、文件位置、文件名、autoload 生成结果和入口路径已经连通。如果仍然是 false，按这个顺序回看：当前工作目录是否正确、require 是否指向当前项目、文件大小写是否一致、类文件是否真的声明了目标命名空间，以及 autoload_psr4.php 是否在本次修改后重新生成。

图2：生成的映射文件、项目 autoload 入口与 class_exists 验证之间的静态关系。

常见问题

改了 composer.json 后一定要删除 vendor 吗？

不一定。只调整自有代码的 PSR-4 映射时，先运行 composer dump-autoload；删除并重新安装依赖会增加网络和版本变化因素。

为什么 macOS 能加载，Linux 却失败？

最常见原因是目录或文件大小写不一致。开发机文件系统的大小写行为可能更宽松，而 Linux 通常严格区分大小写，所以应让 namespace、目录名、文件名和类名完全一致。

什么时候使用 --optimize？

它适合部署时生成更快的 class map，不负责修正错误的 namespace 或目录。先让普通的 dump-autoload 和 class_exists 验证通过，再把优化作为部署步骤。

把排查固定成四个对照项

遇到 Composer 的类找不到，固定对照“完整类名、PSR-4 前缀、项目相对目录、真实文件名”四项；然后重新生成 autoload，最后用当前项目的 class_exists 验证。这样可以把问题限定在可观察的映射关系内，避免把路径错误误判成依赖安装问题。