classmap 是 Composer 生成的类名到文件路径的静态映射表，支持无命名空间类、全局函数等；需在 composer.json 的 autoload.classmap 中配置路径并执行 dump-autoload 生效。
classmap 是什么，为什么它能加载非命名空间类
classmap 是 Composer 生成的扁平化类名到文件路径的映射表，不依赖 PSR-4 或 PSR-0 的命名规则或目录结构。只要类定义在文件里（哪怕没 namespace），且该文件被扫描进 classmap，Composer 就能在 autoload_classmap.php 中写入 'ClassName' => '/path/to/file.php' 这样的键值对，运行时直接查表 require —— 所以它天然支持无命名空间类、全局函数、甚至 __autoload 兼容写法。
如何配置 composer.json 启用 classmap 扫描
在 composer.json 的 "autoload" 段中添加 "classmap" 数组，填入需扫描的目录或文件路径（支持 glob）：
{
"autoload": {
"classmap": [
"lib/",
"src/legacy/",
"functions.php",
"vendor/some-old-package/classes/"
]
}
}
注意：classmap 路径是相对于 composer.json 所在目录的；修改后必须执行 composer dump-autoload（或 composer install/update）才会重新生成映射文件。
- 不要把
vendor/整体加进去 —— Composer 默认已处理其 autoload，重复扫描会拖慢 dump 速度 - 避免使用过于宽泛的 glob（如
"*.php"），容易误扫测试文件或配置文件 - 若只有一两个旧类，直接写死文件路径比扫整个目录更可控
非命名空间类被忽略的常见原因和修复
即使配了 classmap，仍可能加载失败，典型现象是 Class 'LegacyHelper' not found，原因包括：
- 类定义文件里用了
require或include引入其他文件，但那些文件没被 classmap 扫到 —— classmap 只管“当前文件是否声明了类”，不递归解析依赖 - 类名与文件名不一致（比如
LegacyUtil.php里定义了class LegacyHelper），这本身没问题，但某些 IDE 或静态分析工具会报错，容易误判 - 文件编码含 BOM 或存在语法错误（如漏分号、未闭合括号），导致 Composer 解析类名失败，该文件会被跳过，且不报错 —— 可用
composer dump-autoload -v查看跳过日志 -
composer.json放在子目录，而 classmap 路径写的是相对父目录的，实际找不到路径
验证 classmap 是否生效的实操步骤
别只信 dump-autoload 成功提示，要确认映射真写进去了：
- 打开
vendor/composer/autoload_classmap.php，搜索你的类名（如LegacyHelper），确认有对应路径条目 - 在代码中临时加一句：
var_dump(class_exists('LegacyHelper', false));—— 第二个参数设为false表示不触发自动加载，仅查已知映射，可排除 PSR 规则干扰 - 如果类存在但方法调用报
Call to undefined method，大概率是类文件里有语法错误，导致类未被正确定义，而非加载问题
classmap 的本质是“静态快照”，一旦生成就不会动态更新。改了类名、挪了文件、新增了类，都得重跑 composer dump-autoload，这点和 PSR-4 的实时映射完全不同，容易被忽略。
