classmap 是 Composer 静态扫描指定目录中 .php 文件内声明的类、接口、trait 并生成路径映射表，仅在执行 composer dump-autoload 时生成，不监听文件变化，不解析命名空间，重复类名后覆盖前，与 PSR-4 并存时按加载顺序（psr-4 优先）匹配。
classmap 生成原理：不是自动监听，而是静态扫描
Composer 的 classmap 不是运行时动态加载机制，也不监听文件变化。它只是在执行 composer dump-autoload（或安装/更新时）一次性扫描你指定的目录，把所有 PHP 文件里的类、接口、trait 名字和对应文件路径写进 vendor/composer/autoload_classmap.php。之后加载靠的是这个“查表”，而不是实时解析。
所以别指望改了文件不重跑命令就能生效；也别误以为加了 classmap 就能绕过 PSR-4 自动加载规则——它只是多一条并行的查找路径。
- 只扫描
.php文件（不含.inc或其他后缀） - 不解析命名空间嵌套结构，只提取
class、interface、trait声明后的第一个标识符 - 如果一个文件里定义多个类，全部会被收录
- 重复类名会导致后扫描到的覆盖先扫描到的（不报错，但行为不可控）
怎么在 composer.json 里配 classmap 目录
直接往 "autoload" 或 "autoload-dev" 的 "classmap" 字段里填路径数组就行。路径支持相对项目根目录的字符串，也支持通配符 *（但不支持 ** 递归）。
常见写法示例：
"autoload": {
"classmap": [
"src/legacy/",
"lib/helpers.php",
"scripts/*.php"
]
}
- 目录路径末尾带斜杠表示“该目录下所有 .php 文件”，不带斜杠则当作具体文件处理
-
scripts/*.php这种通配写法只在运行composer dump-autoload时展开一次，不会随文件增删自动更新 - 若路径不存在，Composer 会静默跳过（不报错），容易误以为配置生效了——建议执行后检查生成的
vendor/composer/autoload_classmap.php里有没有你预期的类 - 开发阶段频繁增删类文件时，记得每次手动跑
composer dump-autoload，否则新类不会被加载
classmap 和 PSR-4 混用时谁优先
没有“优先级”概念。Composer 加载器是按顺序尝试各 autoload 类型：先 psr-4，再 psr-0，然后才是 classmap，最后是 files。一旦某类在前面的类型中匹配成功，就不会继续往后找。
这意味着：
- 如果你在
psr-4里已经映射了"App\"→"src/"，又在classmap里扫了"src/"，那 classmap 里同名的类永远用不上 - 想让 legacy 类走 classmap 而非 PSR-4，就得确保它们不在任何 PSR-4 映射范围内（比如挪到
legacy/目录，并且不被 PSR-4 规则覆盖） - 调试加载问题时，可临时注释掉其他 autoload 类型，单独验证 classmap 是否工作
为什么 dump-autoload 后类还是找不到
最常踩的坑不是配置写错，而是没意识到 classmap 只认“声明的类名”，不认文件名或路径逻辑。
- 检查目标 PHP 文件里是否真有
class Xxx、interface Yyy等有效声明（空文件、只有函数、只有命名空间声明都不行） - 确认文件编码是 UTF-8 无 BOM，BOM 会导致解析失败，classmap 条目为空
- Windows 下路径分隔符混用（
vs/）一般不影响，但某些老旧 Composer 版本对含中文路径支持差，建议全用英文路径 - 运行
composer dump-autoload -o（优化模式）会强制重建 classmap，但也会忽略未声明类的文件——这不是 bug，是设计行为
classmap 的本质是“懒人索引”，适合老项目迁移、工具脚本、或无法规范命名空间的场景。它省事，但失去 PSR-4 的语义清晰性和 IDE 支持。用之前，先想清楚你到底需要的是“能加载”，还是“可维护”。
