classmap 是 Composer 自动生成的“文件路径到类名”静态映射表，适用于非 PSR 规范遗留代码、纯函数文件及极致性能场景；需在 composer.json 中声明扫描路径，并手动运行 dump-autoload 更新。
Composer 的 classmap 不是“手动配置类映射”的工具，而是通过扫描文件自动生成的加载机制；它不支持运行时动态注册或手写映射规则。
classmap 是什么，什么时候该用它
classmap 是 Composer 生成的一种“文件路径到类名”的静态映射表，本质是一张 PHP 数组（vendor/composer/autoload_classmap.php），由 composer dump-autoload --classmap-authoritative 或 composer install 自动构建。它适用于：
- 没有遵循 PSR-0/PSR-4 命名规范的遗留代码（比如类名含下划线、目录结构混乱）
- 纯函数文件或含全局类定义的杂项脚本（如
helpers.php、defines.php） - 需要极致加载性能且能接受“修改文件后必须重生成”的场景（因 classmap 不支持自动发现新文件）
如何让 composer 扫描并生成 classmap
在 composer.json 中声明要扫描的目录或文件，Composer 会在执行 dump-autoload 时递归解析其中所有 PHP 文件，提取 class、interface、trait、enum 声明并建立路径映射：
{
"autoload": {
"classmap": [
"src/legacy/",
"src/utils/helpers.php",
"lib/"
]
}
}
注意：
- 路径可以是目录（递归扫描）或具体文件（只解析该文件）
- 扫描结果不依赖文件内是否写了
namespace，哪怕全在全局命名空间也照收 - 若同时配置了
psr-4和classmap，classmap 优先级更高（先查 classmap 表，命中则直接 require；未命中才走 PSR 规则） - 添加/删除文件后，必须手动运行
composer dump-autoload，否则新类不会被加载
classmap 模式下的常见错误和陷阱
最典型问题是“类找到了但报错：Class not found”，往往不是映射失败，而是以下原因：
-
composer dump-autoload没运行，或运行时没加--classmap-authoritative（后者可禁用自动发现，强制只走 classmap，便于排查） - 扫描路径写错，比如写成
"src/legacy"（缺末尾斜杠）——Composer 会当作文件而非目录，跳过扫描 - 类文件里用了
__autoload或spl_autoload_register干扰了 Composer 的加载器 - 同一个类名在多个 classmap 路径中被重复定义（Composer 默认不报错，但运行时行为不确定）
- Windows 下路径分隔符混用导致 classmap 生成的键名与实际
require时的路径不一致（建议统一用正斜杠或让 Composer 自处理）
classmap 和 optimize-autoloader 的关系
composer install --optimize-autoloader 或 composer dump-autoload -o 会启用 classmap 优化，但它的作用不止于 classmap：
- 对所有 PSR-4/PSR-0 命名空间，也生成扁平 classmap（即把 namespace → dir 映射转为 class → file 映射）
- 此时即使没在
autoload.classmap里显式声明，PSR 类也会进最终的autoload_classmap.php - 所以
-o是“加速加载”的通用手段，而显式写"classmap": [...]是“兜底加载非标准代码”的专项手段
真正需要手写 classmap 配置的场景其实不多，多数时候用好 PSR-4 + -o 就够了；一旦写了，就得记住：它不活，得常刷。
