classmap 是 composer 的静态类映射自动加载机制，用于加载无命名空间、老旧或非 psr 标准的类文件；需在 composer.json 中配置 classmap 路径并运行 dump-autoload 生效。
classmap 是什么，什么时候该用它
classmap 是 Composer 提供的一种类自动加载机制，本质是把指定目录下所有 PHP 文件里的类名提前扫描出来，生成一张静态映射表（vendor/composer/autoload_classmap.php）。它不依赖文件命名或 PSR-4 规则，适合加载老旧代码、无命名空间的类、或动态生成的类文件。
常见使用场景包括：集成遗留项目、加载 lib/ 或 classes/ 这类扁平目录、或者某些第三方库没遵循 PSR 标准但又必须 autoload。
在 composer.json 中配置 classmap 字段
直接在 autoload 或 autoload-dev 下添加 classmap 数组即可。注意它接收的是路径列表，不是 glob 模式，也不支持通配符 —— 但可以写目录，Composer 会递归扫描。
示例：
{
"autoload": {
"classmap": [
"lib/",
"src/Utils.php",
"legacy/Database.class.php"
]
}
}
关键点：
- 路径是相对于
composer.json所在目录的，不能以/开头（否则会被忽略） - 写文件路径时，Composer 会只扫描该文件本身；写目录时，会递归扫描所有
*.php和*.inc - 修改后必须运行
composer dump-autoload才生效，install或update也会触发 - 如果同时配置了
psr-4和classmap，classmap 的优先级更低 —— 类名冲突时，PSR-4 规则匹配上的会先被加载
classmap 加载失败的典型现象和排查方法
最常见的是 “Class not found”，但错误堆栈里看不到 classmap 相关线索，容易误判为 PSR-4 配置问题。
排查步骤：
- 检查
vendor/composer/autoload_classmap.php是否真包含目标类名 —— 如果没有，说明扫描没覆盖到，确认路径拼写、大小写、是否被 .gitignore 排除 - 运行
composer dump-autoload -o（优化模式）会强制重建 classmap，顺便验证是否语法错误导致跳过 - 用
composer show --platform看当前 autoload 配置是否已加载，或加-v参数看 dump 过程中有没有 warning - Windows 下路径分隔符一般不影响，但若手动拼接路径用了反斜杠且没转义，可能被解析为空字符串
性能与维护注意事项
classmap 的优势是加载快（纯数组查找），缺点是“不活”—— 新增类文件后不会自动感知，必须重新 dump。
所以它不适合高频迭代的开发目录，更适合稳定、低频变更的辅助类库。
另外，classmap 会显著增大 autoload_classmap.php 文件体积，尤其扫整个 vendor/ 或大目录时。生产环境建议配合 -o 使用，避免每次 require 都查磁盘。
一个容易被忽略的细节：autoload-dev 里的 classmap 只在开发环境下生效（比如测试工具类），上线前若没跑 composer install --no-dev，可能导致类意外可用，上线后报错。
