classmap 是 composer 唯一能加载无命名空间、类名与文件名不一致或定义在 .inc 文件中的类的方案；必须配置在 autoload.classmap 数组中并执行 composer dump-autoload 才生效。
classmap 是什么，什么时候必须用它
classmap 不是“备选加载方式”，而是 Composer 唯一能加载**无命名空间、类名与文件名不一致、甚至类定义在 .inc 文件里**的方案。PSR-4 完全跳过这类文件——它只认 namespace 和路径拼写规则。
典型场景包括：
- 老项目里的
MyDB.php里写了class Database { } -
config.php中直接定义class ConfigLoader { }，没命名空间 - 第三方库用了
.inc后缀（如某些 Zend Framework 1 遗留代码）
只要文件中是静态 class X { } 声明，classmap 就能扫到；但如果是 eval("class X {}") 或 class_alias()，它就完全无视。
怎么在 composer.json 里配 classmap 才生效
必须写进 autoload.classmap 数组，且新增或改路径后，一定得手动运行 composer dump-autoload，否则什么都不会变。
配置示例：
{
"autoload": {
"classmap": [
"lib/",
"includes/functions.php",
"legacy/DB_*.php"
]
}
}
注意这些细节：
- 目录会被递归扫描所有
.php、.inc、.hh文件（不扫.txt或.sql） - 支持 glob 表达式（如
legacy/DB_*.php），但 Composer ≥ 2.2 才支持，旧版本只认目录或完整路径 - 路径必须真实存在，否则
dump-autoload会报 warning（但继续执行） - 大小写敏感：Windows/macOS 可能不报错，部署到 Linux 就
Class not found—— 类名、文件名、路径大小写必须完全一致
classmap 和 PSR-4 混用会不会冲突
不会冲突，但有明确优先级：PSR-4 先查，没命中才轮到 classmap。这意味着：
- 如果一个类既符合 PSR-4 规则（比如
App\User→src/User.php），又出现在 classmap 扫描范围内，PSR-4 的路径永远优先生效 - 把已由 PSR-4 覆盖的目录（如
"src/"）再加进classmap，只会拖慢dump-autoload速度、增大autoload_classmap.php体积，毫无收益 - 两个同名类（如都叫
User）分别在不同文件里定义？classmap 只记录第一个扫描到的，后面那个彻底被忽略——它不做命名空间隔离
开启 --classmap-authoritative 为什么反而报错
这个开关的意思是：“所有类都必须来自 classmap，别再 fallback 到 PSR 查找了”。它能显著提速，但前提是——你得确保所有运行时可能 new 出来的类，都被 classmap 扫到了。
常见报错原因：
- 新写的类不在任何 autoload 规则里（比如放在
utils/下但没加进classmap数组） - 用了
"files"加载全局函数（如"src/Helpers.php"），而--classmap-authoritative不管files，这类文件必须保留原配置，不能指望 classmap 替代 - 删了
vendor/composer/autoload_classmap.php却忘了重新dump-autoload，缓存残留导致映射失效 - 某些框架逻辑（如 Laravel Facade）靠
class_exists()做运行时检测，classmap-authoritative 下未声明的类直接返回false，可能触发异常分支
真正难的不是配对，是确认“哪些类必须被扫到”——尤其是那些散落在 legacy/、thirdparty/ 甚至 tests/ 里的冷门工具类，漏一个，上线就炸。
