PHP Composer autoload files 和 classmap 应该怎么选

在 PHP 项目里，Composer 的自动加载配置经常被简化成“能加载就行”。真正容易出问题的是把函数文件、普通类和遗留目录混在一起：files 的加载时机与 classmap 不同，二者也都不是常规命名空间类的首选方案。简单判断是：需要主动引入的全局函数用 files，无法按 PSR-4 组织的类用 classmap，新代码和结构规整的类优先用 PSR-4。

如果目标是“引入 Composer 后就有一组函数”，选 files；如果目标是“按扫描结果找到不规范目录里的类”，选 classmap。类一旦能稳定遵循命名空间到文件路径的约定，就优先改成 PSR-4。

先看加载对象：函数、遗留类还是规范类

files 解决的是函数不能按类名触发自动加载的问题。例如项目有一个包含 money_format_local()、request_id() 的函数文件，调用点只需要函数存在，并没有一个可供 PHP 通过类名寻找的对象。这类文件适合显式列入 autoload.files。

classmap 则面向“类存在，但文件路径不符合 PSR-4”的情况。老项目可能把多个全局类、历史目录或第三方源码混在一起，Composer 可以扫描其中的 .php 和 .inc 文件，把找到的类写入类映射。它不要求你先改造命名空间和目录，但也因此不如 PSR-4 直观。

如果类名为 Acme\\Billing\\Invoice，文件稳定位于 src/Billing/Invoice.php，就没有必要用扫描来“猜”它在哪里。PSR-4 直接把命名空间前缀映射到目录，新增类也不需要因为每个文件变化而重新生成类表。

files 和 classmap 的配置差异

下面是一份刻意缩小的示例：函数文件指向具体文件，classmap 指向需要扫描的旧目录，规范类仍然交给 PSR-4。JSON 不支持注释，因此把解释放在代码块前后，避免破坏 composer.json 的格式。

{
  "autoload": {
    "psr-4": {
      "Acme\\\\Billing\\\\": "src/Billing/"
    },
    "files": [
      "src/Support/functions.php"
    ],
    "classmap": [
      "legacy/",
      "src/Legacy/Report.php"
    ]
  },
  "autoload-dev": {
    "psr-4": {
      "Acme\\\\Billing\\\\Tests\\\\": "tests/"
    }
  }
}

这里的关键不是三种写法越多越好，而是每种写法只承担自己的边界。files 会在 Composer 自动加载器注册后被包含，根包的 files 位于依赖文件之后；因此函数文件应该尽量只声明稳定、低副作用的函数。classmap 会把扫描结果写入生成的 vendor/composer/autoload_classmap.php，不要把包含测试夹具、示例或不应进入生产的目录直接扫进去。

改完配置后，为什么还要 dump-autoload

Composer 的配置和 vendor/composer 里的生成文件不是同一层。新增 files 或 classmap 路径后，先重新生成自动加载器，再从一个最小入口检查结果：

# 重新生成 Composer 自动加载文件
composer dump-autoload

# 查看类映射是否已生成；路径是相对项目根目录
test -f vendor/composer/autoload_classmap.php && echo "classmap ready"

number(), PHP_EOL;

若函数调用失败，先检查 files 中的相对路径和函数是否真的定义在该文件内；若类找不到，先检查命名空间、文件名大小写和 PSR-4 前缀。只有在类结构不符合约定时，才继续检查 classmap 是否覆盖了正确目录。对 classmap 来说，改完目录或新增类后不重新生成，旧映射不会自动代表最新文件集合。

按维护成本做选择

一个实用的迁移顺序是：先把确定是函数的文件留在 files，再给遗留类设置窄范围 classmap，同时为新类建立 PSR-4 目录。等旧类被逐步改成命名空间后，缩小 classmap，而不是把整个项目的 src/ 永久交给扫描器。

常见问题：配置能用，但结果不符合预期

classmap 能不能替代所有 PSR-4 配置？

能覆盖一部分类，但不建议这样做。它依赖扫描和生成结果，目录越大，越难看出类名与路径的对应关系；规范类用 PSR-4 更易维护。

files 里的函数会在调用时才加载吗？

不是。只要入口引入 Composer 的 vendor/autoload.php，files 规则就会按 Composer 的加载顺序包含，所以应控制文件副作用。

只改了 classmap 目录，为什么新类仍然找不到？

通常是生成物还没更新。重新运行 composer dump-autoload，再检查类的命名空间、文件名大小写和扫描路径是否一致。

生产环境要不要把 tests 放进 classmap？

通常不需要。测试类应放在 autoload-dev，并避免在生产安装时把开发自动加载规则带入运行路径。

Composer 自动加载选型的核心不是记住两个字段，而是先识别加载对象和加载时机：函数文件用 files，非规范类用有限范围的 classmap，能遵循命名空间路径约定的类用 PSR-4。配置变更后重新生成，并把生产类、测试类和遗留类分开，后续排错会简单很多。