根本原因是Docker构建层对vendor/和composer.lock变更敏感，且composer install若放在final阶段则中间产物被丢弃；必须先单独COPY composer.json/composer.lock，再在builder阶段执行install，final阶段仅COPY vendor。
为什么 composer install 在 Docker 多阶段构建里总不缓存？
根本原因不是 Composer 本身，而是 Docker 构建层对 vendor/ 目录和 composer.lock 的变更敏感度没对齐。你改了一行 composer.lock，Docker 就从那一层全重来；更糟的是，如果 composer install --no-dev 放在最终镜像阶段，前面所有依赖下载、解压、autoloader 生成动作都白做——因为中间镜像被丢弃，缓存根本用不上。
- 确保
composer.lock在COPY阶段早于composer install，且该COPY行只包含composer.json和composer.lock（不要带src/或其他变动频繁的文件） - 把
composer install放在构建中间阶段（如builder），而不是 final 阶段；final 阶段只COPY --from=builder /app/vendor /app/vendor - 加
--ignore-platform-reqs要谨慎：它绕过 PHP 扩展检查，可能导致 runtime 错误，仅当构建环境 PHP 版本与运行时严格一致时才安全
docker build 怎么让 Composer 缓存复用率超过 90%？
关键不是“加缓存”，而是让缓存失效点尽可能靠后。Docker 按指令顺序逐层缓存，只要某一层失效，后续全失效。所以要把最稳定的部分（composer.lock）放在最前，最易变的部分（代码）放在最后。
- 分三步
COPY：先COPY composer.json composer.lock ./，再RUN composer install --no-dev --prefer-dist --optimize-autoloader，最后COPY . . - 使用
--build-arg COMPOSER_CACHE_DIR=/tmp/composer-cache并在RUN前挂载 volume（仅限本地构建调试），CI 环境建议直接用 BuildKit 的cache-from+ registry cache - 避免在
RUN composer install前执行apt-get update类命令混在同一层——它们会污染缓存哈希，哪怕内容没变，Docker 也可能判定为不同层
多阶段构建中 vendor/ 复制后为何 autoload 失效？
常见于未同步 vendor/autoload.php 生成路径或 autoloader 权限问题。Composer 默认生成的 autoloader 依赖绝对路径，而多阶段复制后，若工作目录或用户 UID 不一致，include 会失败，报错类似 failed to open stream: No such file or directory。
- 在 builder 阶段执行
composer install后，立刻运行php -d display_errors=Off -r "require 'vendor/autoload.php';"验证可加载 - final 阶段
COPY --from=builder时，确保目标路径与代码中require的路径一致（例如都是/app/vendor/autoload.php） - 如果用非 root 用户运行 final 镜像，提前在 builder 阶段
RUN chown -R www-data:www-data vendor/，否则权限丢失导致 require 失败
BuildKit 下如何用 cache-from 复用远程 Composer 层？
BuildKit 的 inline 缓存模式默认不上传层，必须显式配置 registry 缓存源。光写 --cache-from type=registry,ref=... 不够，还要让 Composer 安装过程不跳过已存在的包——这依赖于 --prefer-dist 和一致的 hash 计算逻辑。
- 启用 BuildKit：
DOCKER_BUILDKIT=1 docker build ... - 推送缓存镜像：
docker build --target builder --output type=image,name=your-registry/app-builder-cache,push=true . - 拉取并复用：
--cache-from type=registry,ref=your-registry/app-builder-cache:latest - 务必在
composer install前加RUN mkdir -p /root/.composer/cache，否则某些旧版 Composer 会拒绝写入缓存目录导致降级为 source 模式，拖慢构建
真正卡住构建速度的往往不是 Composer 本身，而是缓存策略和路径语义没对齐。尤其要注意 COPY 的粒度、--no-dev 的时机、以及 final 阶段的用户上下文是否继承了 builder 阶段的文件权限和路径假设。
