PHP Composer自动加载优化与开发环境差异的配置方法

PHP Composer 自动加载的关键不是把所有环境都调到同一个开关，而是把“类如何被找到”和“什么时候生成映射”分开处理：开发环境保留 PSR-4 的灵活性，生产发布时使用 --no-dev --optimize-autoloader 生成稳定的 classmap。只有确认项目没有运行时生成类，才考虑 --classmap-authoritative；如果只是想缓存命中与未命中的结果，则选择 APCu 路线。

推荐的默认配方是：源码用 PSR-4，测试放进 autoload-dev；本地不要强行 authoritative，生产安装依赖时统一加 --no-dev --optimize-autoloader，再根据动态类风险决定是否启用 authoritative。

• 开发：新增类后可以直接被 PSR-4 规则发现。
• 生产：在构建阶段生成 classmap，减少文件系统探测。
• 边界：authoritative 会把 classmap 外的类视为不存在，不能盲开。

先把开发与生产的目标分开

Composer 官方把自动加载优化定位为生产优化：PSR-4 在开发时方便，因为新增类不必每次都重建映射；生产代码则是在发布时确定的，适合提前生成 classmap。也就是说，本地体验与线上启动速度的优先级不同，不能用“本地能加载”直接推断“线上任何动态类都能加载”。

项目的自动加载入口仍然是 vendor/autoload.php。它会注册 Composer 生成的加载器；PHP 本身则通过 SPL 自动加载器在类、接口、trait 或枚举尚未定义时尝试加载。不要再围绕 PHP 8 项目设计旧式 __autoload()，该函数已经移除。

用 PSR-4 作为源码映射

最小的 composer.json 可以把 App\ 映射到 src/，并把测试命名空间独立放在 autoload-dev。命名空间前缀要带结尾反斜杠，否则相似前缀可能发生匹配歧义。

{
  "autoload": {
    "psr-4": {
      "App\\\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "App\\\\Tests\\\\": "tests/"
    }
  }
}

例如 App\Service\OrderService 对应 src/Service/OrderService.php。开发依赖和测试类不应污染生产自动加载规则，发布时用 --no-dev 安装可以同时避开测试依赖。

发布时生成优化 classmap

发布脚本应在干净的依赖安装阶段生成优化映射，而不是让线上进程临时修补。常见命令如下：

# 生产安装：不安装开发依赖，并把 PSR-4/PSR-0 规则转换为更快的 classmap
composer install --no-dev --optimize-autoloader

# 只重建自动加载文件时使用；不会重新解析依赖版本
composer dump-autoload --optimize

--optimize-autoloader 会让已知类直接从映射得到文件路径，减少逐层文件系统检查。Composer 文档也提醒，这种优化应放在生产环境；开发时新增或删除类后如果忘记重建，反而会得到“明明有文件却找不到”的假象。

如果项目有测试目录、示例目录或仅供开发的类，优先使用 autoload-dev；若某些兼容旧目录结构的类不符合 PSR-4，再用明确的 classmap 指向它们，不要把整个项目无差别扫描成一张不可解释的大表。

谨慎启用 authoritative 或 APCu

classmap-authoritative 会自动包含 classmap 优化，并且规定：classmap 中没有的类不再回退到 PSR-4 文件系统查找。它能把未命中路径压到很短，但代价是运行时生成的类、部署后才出现的类或某些依赖的特殊加载行为可能变成 Class not found。

# 只有确认所有类在发布时已经存在时才使用
composer install --no-dev --classmap-authoritative

# 另一条路线：保留回退能力，并缓存类存在与否
composer install --no-dev --optimize-autoloader --apcu-autoloader

authoritative 与 APCu 是同一层级的两种选择，不能同时启用。判断方法很简单：如果框架、插件系统或依赖会在请求期间生成类，先用普通 classmap，或选择 APCu；如果应用是固定代码集、发布包不可变，再评估 authoritative。

用最小检查确认配置生效

不要只看命令退出码，至少确认四件事：生产依赖目录没有测试包；vendor/composer/ 下生成了对应的 classmap；代表性业务类可以通过入口文件加载；项目没有把运行时生成类误判为静态类。

最后把自动加载模式写进发布清单：开发使用默认 PSR-4，生产使用 --no-dev --optimize-autoloader，只有经过动态类排查后才升级到 authoritative。这样既保留本地改代码的反馈速度，也让线上加载路径可重复、可解释。

相关问题

为什么本地新增类能用，线上却报 Class not found？ 常见原因是线上使用了旧的 classmap，或启用了 authoritative 但新类没有在构建阶段生成；重新生成自动加载文件并确认发布包内容即可定位。

classmap 越大越好吗？ 不是。它应覆盖生产需要的固定类集合；测试、示例和动态生成类混入后，会增加构建与排错成本，甚至掩盖真正的加载边界。