PHP Composer autoload-dev 为何在线环境找不到类

线上执行 composer install --no-dev 后，如果业务代码突然报“Class not found”，先别急着改命名空间。最常见的原因是这个类被放进了 autoload-dev，或者它依赖的包只声明在 require-dev。--no-dev 会同时跳过开发依赖和开发自动加载规则，所以本地能运行、线上找不到类其实是配置边界一致生效的结果。

官方地址：https://getcomposer.org/doc/

一、先把线上缺类拆成两种依赖

Composer 里有两组容易混淆的开关：require 与 require-dev 决定“包是否安装”，autoload 与 autoload-dev 决定“哪些项目代码进入自动加载器”。生产环境只要使用 --no-dev，前一组的开发包和后一组的开发规则都会被排除。

例如下面的配置里，Tests\\ 目录消失是正常的；但如果线上控制器引用了 App\\Service\\Report，它就不能留在 autoload-dev 中。配置块是严格 JSON，因此不在其中插入注释，判断依据写在代码前后。

{
  "require": {
    "psr/log": "^3.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0"
  },
  "autoload": {
    "psr-4": {
      "App\\\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Tests\\\\": "tests/"
    }
  }
}

判断口诀很简单：线上请求会实例化的类属于 autoload；只在 PHPUnit、静态分析或本地脚本中出现的类属于 autoload-dev。如果类本身属于运行时，但它依赖的第三方包在 require-dev，同样会在生产环境缺失。

二、用 --no-dev 复现并定位生成边界

先在与生产相同的干净目录验证，不要直接删除线上 vendor。开发机可以先保存现有目录，然后执行下面的命令；注释说明了每个参数的目的。

# 生产模式安装锁定版本，跳过 require-dev 和 autoload-dev
composer install --no-dev --prefer-dist --optimize-autoloader

# 只重建生产模式自动加载器，不把开发目录重新加入
composer dump-autoload --no-dev --optimize

随后检查三处：第一，看 composer.json 中类所在目录是不是写在 autoload-dev；第二，看类依赖的包是不是只在 require-dev；第三，在 vendor/composer/autoload_psr4.php 中确认生产命名空间映射是否存在。这个文件是 Composer 生成物，只用于定位，不能作为长期手工维护点。

如果 composer install 报锁文件与配置不一致，先在依赖变更的开发环境执行更新并提交新的 composer.lock，不要在生产机临时执行无约束的 composer update。若映射存在但仍报错，再检查命名空间大小写、PSR-4 目录和文件名是否一致。

三、把生产类移到 autoload 并重建产物

修复的核心不是让生产环境安装所有开发包，而是把运行时边界声明正确。以 App\\Service\\Report 为例，文件应位于 src/Service/Report.php，命名空间应与 PSR-4 前缀对应；测试类继续留在 tests/ 与 autoload-dev。

调整 composer.json 后，在开发或 CI 环境重新生成锁文件和自动加载器，再把两者一起交付。这里的原则是“声明先正确，生成物再更新”：仅复制一个本地 vendor 目录，可能把错误的开发状态带到线上。

四、按环境选择 Composer 命令

开发环境需要 PHPUnit、Mock 和调试工具，可以使用默认的开发安装；CI 通常要先跑测试再构建部署包；生产环境则固定使用 --no-dev。不要让同一个部署脚本在不同机器上依赖 Composer 上一次运行留下的状态。

如果项目是库而不是可直接部署的应用，还要站在“消费者”角度看 require-dev：库自己的测试工具可以留在开发依赖，但库对外暴露的运行时类不能依赖只在开发环境安装的包。必要时在构建阶段用一个最小入口做类加载烟雾检查，检查通过即可，不要用它替代依赖声明。

五、用清单防止类再次消失

• 线上入口会调用的 PHP 类，目录映射是否在 autoload，而不是 autoload-dev？
• 线上实例化的第三方包，是否在 require，而不是 require-dev？
• composer.lock 是否与 composer.json 一起提交并在构建阶段使用？
• 部署命令是否明确包含 --no-dev，并在同一模式下重建自动加载器？
• 命名空间、目录和文件名的大小写是否与 PSR-4 映射完全一致？

真正的修复结果应该是：生产机不安装开发工具，但业务入口仍能从 vendor/autoload.php 找到所有运行时类；测试代码则只在开发或 CI 环境可见。这样既保持发布包干净，也不会把“本地能跑”误当成“线上依赖声明正确”。

相关问题

线上直接执行 composer install 会默认安装开发依赖吗？

会。默认安装 require-dev，生产部署应显式使用 --no-dev，让部署意图可读且不依赖环境变量。

把 tests/ 从 autoload-dev 移到 autoload 能解决问题吗？

只能让测试类进入生产自动加载器，不能解决业务类放错目录或第三方包仍在 require-dev 的问题。应按类的实际运行场景分别归类。

为什么改了 composer.json 仍然找不到类？

常见原因是没有在变更环境重建自动加载器、生产继续使用旧 vendor，或锁文件没有随配置一起更新。先清理构建产物并用同一条生产命令重新安装。