composer dump-autoload --classmap-authoritative 启用类加载权威模式，强制仅通过 autoload_classmap.php 查找类，禁用运行时 PSR-4/PSR-0 目录扫描，提升性能但要求构建时 classmap 完整覆盖所有生产类。
什么是 composer dump-autoload --classmap-authoritative
它告诉 Composer：类文件位置完全由 vendor/composer/autoload_classmap.php 决定，不再动态扫描 PSR-4/PSR-0 命名空间目录。运行时跳过所有文件系统查找，直接查表返回路径。
这个模式只在生产环境有意义——开发中你频繁增删类，每次改完都得重新生成 classmap，反而拖慢迭代速度。
- 启用后，
class_exists()、new ClassName()等操作不再触发file_exists()或opendir()调用 - 不支持动态注册的类（比如通过
spl_autoload_register手动追加的加载器），必须全部纳入 classmap - Composer 2.0+ 默认启用该优化，但需显式加
--classmap-authoritative才真正生效（否则仍保留 fallback 行为）
如何正确启用并验证是否生效
关键不是执行命令，而是确认最终生成的 autoloader 是否真的丢弃了命名空间扫描逻辑。
执行以下命令生成权威 classmap：
composer dump-autoload --classmap-authoritative --no-dev -o
然后检查生成的 vendor/autoload.php 是否包含 'classmap-authoritative' => true；再打开 vendor/composer/autoload_real.php，搜索 findFile 方法——如果里面只有 if ($classMap = $this->classMap) 分支，且没有 foreach ($this->prefixesPsr4 或 $this->fallbackDirsPsr4 相关代码，说明已彻底禁用动态查找。
-
--no-dev必须加上：dev 依赖的类不会进 classmap，残留它们会导致 fallback 触发，破坏权威性 -
-o（optimize）会合并 PSR-4 映射到 classmap 中，但仅当这些命名空间下所有类都实际存在时才安全；若项目有空目录或占位文件（如src/Command/下无 PHP 文件），-o可能漏掉映射 - CI/CD 部署时建议加
--apcu-autoloader一起用，APCu 缓存 classmap 查找结果，进一步减少内存读取开销
常见失效场景和排查方法
线上启用了却没提速？大概率是 classmap 没覆盖全，导致 autoloader 回退到普通模式。
典型问题包括：
- 使用了
files类型自动加载（如"files": ["src/helpers.php"]）：这类文件不会被写入 classmap，但会被单独 require。只要它们存在，就不会触发 fallback；但如果 helper 里又 require 了未声明的类，就会破防 - 类名拼写错误或命名空间与目录结构不一致（比如
App\Services\UserService实际放在src/Services/UserService.php，但composer.json中 PSR-4 映射写成了"App\\": "src/"—— 这种错配会让-o无法正确归入 classmap - 运行
composer dump-autoload时当前工作目录不是项目根目录，导致生成的 classmap 路径是相对的、不可移植的 - 部署后修改了
vendor/外的代码（比如热更新app/下的类），但没重新 dump autoload —— 新类根本不在 classmap 里，首次访问必 500 或 ClassNotFound
为什么不能在 Docker 构建阶段就生成 classmap
可以，但要注意时机。很多镜像在 composer install --no-dev 后立刻 dump-autoload --classmap-authoritative，看似合理，实则危险。
因为 composer install 本身会根据 composer.lock 安装依赖，而某些包的安装脚本（post-install-cmd）可能在之后动态生成类文件（比如 Doctrine Proxy、Laravel Octane 的预热类、自定义的代码生成工具）。如果 classmap 在这些脚本执行前就固化，那些新类就永远进不了 map。
- 推荐做法：先
composer install --no-dev，再php artisan octane:install（或其他生成类的命令），最后composer dump-autoload --classmap-authoritative -o - Dockerfile 中避免把 classmap 生成和 vendor 安装写在同一层，否则缓存失效时容易漏掉重生成步骤
- 如果项目用了 Composer 插件（如
roave/better-reflection）或自定义 autoloader，务必确认它们不依赖运行时文件发现机制——否则开启权威模式后直接罢工
最常被忽略的一点：--classmap-authoritative 不是“开了就快”，它是把类发现成本从运行时转移到构建时，并要求构建过程完整、可重现。一旦 classmap 缺失哪怕一个生产必需的类，后果不是慢，而是崩。
