缓存预热脚本必须在构建阶段执行，将vendor、.composer/cache/files/及bootstrap/cache/文件固化进镜像，并通过--no-dev --prefer-dist --optimize-autoloader --classmap-authoritative --no-scripts参数组合与守卫式PHP脚本确保缓存稳定复用，避免运行时重建和scripts静默失败。
缓存预热脚本必须在构建阶段执行，不能等容器启动
镜像启动时再跑 composer install 就晚了——节点冷启时 .composer/cache/files/ 是空的，vendor 重建、scripts 静默失败，首请求延迟直接翻倍。预热脚本本质是“把缓存固化进镜像”的守卫逻辑，不是运行时补救。
常见错误现象：Script php artisan config:cache handling the post-install-cmd event returned with error code 1，但构建日志只显示 “install completed”。这是因为环境变量缺失、DB 连接不可达，或 config:cache 依赖未生成的 bootstrap/cache/config.php。
- 脚本必须用 PHP 写（非 shell），才能做基础守卫：检查
APP_ENV=production、APP_KEY是否存在、bootstrap/cache/是否可写 - 所有
post-install-cmd命令应封装为函数，失败时exit(1)并输出明确错误，避免被composer install --no-scripts掩盖 - 脚本末尾加
touch bootstrap/cache/*.php，确保文件修改时间早于镜像构建时间，否则运行时会重新生成
怎么让 composer install 真正复用缓存
缓存复用不靠运气，靠三件事同时满足：包文件已存在、元数据未过期、目录权限一致。Docker 构建中常因 COPY 顺序或用户切换导致缓存失效。
典型问题：composer install 明明用了 --prefer-dist，却仍解压 tar.gz；或 cache-dir 挂载了但 repo 缓存没命中。
- 构建前先在 CI 中运行
composer clear-cache --gc，清理过期包，避免缓存膨胀挤掉有效项 -
Dockerfile中COPY composer.json composer.lock ./必须紧挨着RUN composer install，中间不能插入其他COPY或RUN，否则 layer cache 失效 - 若用多阶段构建，builder 阶段需显式设置
COMPOSER_CACHE_DIR=/tmp/composer-cache，并在 final 阶段COPY --from=builder /tmp/composer-cache /root/.composer/cache
--optimize-autoloader 和 --classmap-authoritative 必须配对使用
单独开 --optimize-autoloader 只生成 autoload_classmap.php，但 autoloader 仍会 fallback 到 PSR-4 扫描；加上 --classmap-authoritative 才真正关闭动态查找——这才是性能跃升的关键。
容易踩的坑：--no-dev 不加，dev 包里的类不会进 classmap，一触发就 fallback；或者项目里有 "files": ["helpers.php"]，这类文件不进 classmap，但会强制启用 fallback 分支。
- 命令必须带全：
composer install --no-dev --prefer-dist --optimize-autoloader --classmap-authoritative --no-scripts - 验证是否生效：打开
vendor/composer/autoload_real.php，搜索findFile方法——如果只剩if ($classMap = $this->classMap)分支，且没有$this->prefixesPsr4相关循环，说明已生效 - CI 构建后加一步检查：
grep -q "classmap-authoritative.*true" vendor/autoload.php || exit 1
APCu 缓存和 opcache 配置是最后一道加速屏障
即使 classmap 已权威，如果 PHP 的 opcache 没启用或 validate_timestamps=1，每次请求仍要 recompile autoload_classmap.php；而 APCu 能缓存 classmap 查找结果，进一步省掉数组遍历开销。
线上常见表现：ab -n 100 -c 10 测试中前 5 次响应慢，后续稳定——这不是 Composer 的问题，是 opcache 没热起来。
- PHP 配置必须含：
opcache.enable=1、opcache.enable_cli=1（CLI 场景也需要）、opcache.validate_timestamps=0（生产环境禁用时间戳校验） - 启用 APCu 自动加载器：
composer install --apcu-autoloader，它会在vendor/autoload.php中注入 APCu 缓存逻辑 - 注意：APCu 缓存需进程间共享，FPM 下推荐用
apc.shm_size=64M，并确认apc.enable_cli=1启用
关键点不在脚本写了多少行，而在每一步是否堵死了 fallback 路径：classmap 是否完整、缓存路径是否固化、opcache 是否跳过校验、scripts 是否在无依赖条件下执行。漏掉任意一环，预热就变成假动作。
