classmap是老旧项目接入Composer自动加载的首选方式，它不依赖命名空间或文件名规范，通过扫描指定目录下PHP文件中的class/interface/trait声明生成静态映射表（vendor/composer/autoload_classmap.php），需手动运行composer dump-autoload生效。
classmap 是老旧项目接入 Composer 自动加载的首选方式
老旧框架通常没有命名空间、类名与文件路径无规律、甚至存在动态生成类或 __autoload 遗留逻辑 —— 这类场景下，psr-4 会直接失效，而 classmap 不依赖命名约定，只靠扫描物理文件中的 class、interface、trait 声明就能建表，是唯一能兜底的方案。
它生成的映射是静态的（存于 vendor/composer/autoload_classmap.php），运行时零解析开销，比 PSR-4 更快，但代价是每次增删类文件后必须手动触发 composer dump-autoload。
-
classmap接收的是目录路径数组，不是 glob 模式，不支持**/*.php或lib/*.class.php这类写法 - 可以写单个 PHP 文件（如
"legacy/bootstrap.php"），Composer 会单独解析它里面的类定义 - 若目录下混有非类文件（如配置数组、函数库），不影响扫描 —— Composer 只提取符合语法的类结构声明
- 慎用根目录（如
"."）：可能扫入vendor/、tests/等无关路径，导致映射表臃肿甚至冲突
如何在 composer.json 中正确配置 classmap 路径
把老旧框架的类文件集中目录列进 autoload.classmap，不是猜路径，而是看实际存放位置。比如传统 lib/、classes/、model/、core/ 这些扁平目录，都是典型目标。
示例配置（放在项目根目录的 composer.json 中）：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
{
"autoload": {
"classmap": [
"lib",
"classes",
"model",
"core/functions.php"
]
}
}
- 路径必须相对于
composer.json所在目录；写错相对路径会导致扫描无声失败（无报错，但类不被加载） - Windows 下路径分隔符用
/即可，Composer 内部自动兼容 - 如果旧框架用了类似
My_Class_Name这种下划线分隔的伪命名空间，classmap同样能识别并注册为完整类名，无需额外处理 - 不要和
psr-4混用同一类名前缀：例如"App\"同时出现在psr-4和classmap中，后者会被忽略（PSR 规则优先级更高）
dump-autoload 后仍找不到类？检查这三点
运行 composer dump-autoload 后类还是 Class not found，大概率不是配置问题，而是环境或语义细节没对齐。
- 确认是否执行了
composer dump-autoload（不是install或update）；加--verbose可看到实际扫描了哪些文件 - 检查类文件中是否有语法错误（如
class关键字拼错、PHP 版本不兼容的特性），Composer 扫描时会跳过无法解析的文件，且不报错 - 确认入口文件已引入
vendor/autoload.php—— 很多老项目还在用自定义include链，忘了切换到 Composer 加载器 - 如果类定义在条件块内（如
if (defined('IN_APP')) { class A {} }），Composer 扫描时不会执行代码，这类类无法被发现，需移出条件或改用files方式加载
混合新旧代码时 classmap 和 psr-4 怎么共存
当项目一边是老旧无命名空间类，一边是新写的 App\ 命名空间代码，最稳妥的做法是分而治之：旧代码走 classmap，新代码走 psr-4，两者互不干扰。
示例配置：
{
"autoload": {
"psr-4": {
"App\": "src/"
},
"classmap": ["lib", "model"]
}
}
- Composer 会按顺序尝试加载：先查
psr-4映射，再查classmap表，最后 fallback 到files - 避免让
classmap扫描到src/目录 —— 否则会把新类重复注册，浪费内存，且可能因加载顺序引发意外覆盖 - 如果旧框架里已有少量带命名空间的类（如
Legacy\Helper），可为其单独配一条psr-4规则，不必强求全部塞进classmap
真正容易被忽略的是 classmap 的“静态性”：它不感知文件变更，也不做运行时路径推导。一旦你往 lib/ 里加了个新类，就得再跑一遍 dump-autoload，这点和 PSR-4 的“按需即查”有本质区别。
