Composer如何自动生成类映射？Composer类库加载策略【技术内幕】

Composer 的类映射生成机制，其实存在不少容易踩坑的地方。先说几个核心判断：默认情况下，Composer 不会自动生成 autoload_classmap.php，必须手动执行 composer dump-autoload 并配合正确参数。所谓“自动生成”只是误传，真实流程是静态扫描加手动触发。

为什么 composer dump-autoload 没生成 autoload_classmap.php？

默认不生成 classmap，这是最常被忽略的前提。它只更新 PSR-4/PSR-0 映射逻辑，不会扫描文件、不会写入类名到路径的扁平数组。

• 没加 -o（--optimize-autoloader）或 --classmap-authoritative，就不会触发 classmap 构建
• 项目里根本没配 "classmap" 字段，又没用 PSR-4 声明目录，-o 也无从下手
• 路径写错：比如写成 "lib"（无斜杠）会被当作文本读取，报 Could not scan for classes
• 路径不存在或为空目录，Composer 默认静默跳过，不报错也不收录
• Windows 下混用 和 /，应统一用 /（如 src/legacy/）

composer dump-autoload -o 到底扫了哪些文件？

它只扫描 composer.json 中 autoload 和 autoload-dev 下明确声明的路径，且行为因配置而异：

• 若只配了 PSR-4（如 "App\": "src/"），-o 会递归扫描 src/ 下所有 .php 文件，提取其中 class、interface、trait 声明
• 若额外配了 "classmap": ["lib/", "functions.php"]，则同时扫描这些路径——但 functions.php 里的函数不会进映射表，只有类结构体才会
• 不扫描未在 autoload 中声明的目录（如 tests/ 或 docs/），哪怕它们有合法类
• 符号链接（symlink）会被跳过，不解析
• 条件分支里的类（如 if (false) { class A {} }）仍会被捕获，因为它是词法扫描，不执行代码

生产环境该用 -o 还是 --classmap-authoritative？

二者不是互斥，而是递进关系：--classmap-authoritative 必须配合 -o 使用，否则无效。

• composer dump-autoload -o：生成 autoload_classmap.php，但 fallback 机制仍在——查不到类时仍会尝试 PSR-4 路径拼接和 file_exists()
• composer dump-autoload -o --classmap-authoritative：告诉 autoloader “classmap 就是全部”，查不到直接抛 Class not found，省掉一次 stat() 系统调用
• CI/CD 或 Docker 构建阶段推荐后者，适合不可变部署场景
• 但开发时慎用：改了类名或新增类后不重跑命令，必然报错，IDE 断点和热重载也可能失效
• 若用了 files 加载（如全局 helper 函数），它们会被 require_once 注册，但函数名不会进 classmap —— 这是设计使然，不是 bug

真正容易被忽略的是：classmap 不是“覆盖越多越好”。把整个 src/ 目录塞进去，却没清理掉旧的 PSR-4 配置，会导致映射冗余、体积膨胀，甚至命名冲突。生成后务必检查 vendor/composer/autoload_classmap.php 是否包含你预期的类名，且路径指向正确文件。