必须用--classmap-authoritative的场景是纯生产环境且满足：无动态加载、无运行时注册、无插件式类发现，如Docker最终镜像、封闭部署包、CI构建后容器化PHP应用。
开启 --classmap-authoritative 后，Composer 会完全忽略 autoload.files 和 PSR-4/PSR-0 的动态路径查找，只信任生成的 classmap —— 这意味着漏掉一个 dump-autoload 或类文件没被扫描进 classmap，运行时直接 Class not found。
什么时候必须用 --classmap-authoritative
它不是“越快越好”的开关，而是为「确定无动态加载、无运行时注册、无插件式类发现」的纯生产环境准备的。典型场景：Docker 镜像构建完成后的最终镜像、无用户上传代码的封闭部署包、CI 构建后打入容器的 PHP 应用。
- 你的项目不使用
include/require动态加载类文件（比如某些老式工厂模式） - 没有运行时调用
ClassLoader::addPsr4()或修改自动加载逻辑 - 所有类都通过 Composer 管理，且
composer.json中的autoload和autoload-dev定义完整、准确 - 你愿意在每次增删类文件后手动触发
composer dump-autoload --classmap-authoritative
--classmap-authoritative 和普通 classmap 模式区别在哪
关键不在“有没有 classmap”，而在“是否强制绕过所有其他 autoload 机制”。普通 composer dump-autoload -o 仍保留 PSR-4 fallback；而加了 --classmap-authoritative 后，哪怕 src/Foo/Bar.php 明明符合 PSR-4 规则，只要没被扫进 classmap，new Foo\Bar 就会失败。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 启用后，
ClassLoader::findFile()会跳过所有非 classmap 分支，只查$classMap数组 -
autoload.files列表里的文件仍会被 require_once，但它们定义的类若未出现在 classmap 中，也无法被自动加载 - 性能提升主要来自减少字符串解析和目录遍历，实测通常快 10%–30%，但前提是 classmap 文件本身不大（>5MB 就可能拖慢 opcache 加载）
常见报错和排查步骤
最常遇到的是部署后第一请求就 Fatal error: Class 'Xyz' not found，但本地开发一切正常 —— 很大概率是 classmap 没更新或扫描范围不对。
- 确认执行
composer dump-autoload --classmap-authoritative --no-dev是在目标环境中做的（不是本地），且vendor/autoload.php被重新生成 - 检查
vendor/composer/autoload_classmap.php是否真包含该类名（搜索'Xyz'），注意大小写和命名空间斜杠 - 如果类在
tests/或examples/目录下，它默认不会被扫入 classmap —— 需在composer.json的autoload中显式添加对应路径 - 使用
composer show -p确认当前加载的是不是你认为的那个包版本，不同版本 classmap 内容可能不同
这个模式真正的复杂点不在开启动作，而在于它把“类可见性”从运行时契约变成了构建时事实 —— 一旦 classmap 固化，任何绕过 Composer 自动加载机制的代码（比如 eval()、反射加载、临时 require）都会立刻暴露问题。别把它当成通用加速选项，它是给确定性让路的开关。
