多阶段 Docker 构建中优化 Composer 缓存的核心是精准分阶段：builder 阶段用完整镜像+BuildKit 缓存挂载执行 composer install --no-dev --optimize-autoloader，final 阶段用精简镜像仅复制 vendor/ 和代码，避免残留缓存与 dev 依赖。
在多阶段 Docker 构建中优化 Composer 缓存层，核心是让依赖安装过程能复用已缓存的 vendor 文件，同时避免把 dev 依赖、临时文件、缓存目录等打进最终镜像。关键不在于“怎么清缓存”，而在于“怎么让缓存生效且不残留”。
分阶段分离依赖安装与运行时环境
利用多阶段构建天然隔离的特性，在 builder 阶段完成 composer install，并只复制 vendor 和必要文件到 final 阶段：
- builder 阶段使用带 curl、git、unzip 的完整 PHP 镜像（如 php:8.2-cli），并挂载 composer cache 到构建上下文外的缓存目录（如 --cache-from）或用 BuildKit 的缓存挂载
- final 阶段用极简镜像（如 php:8.2-cli-alpine 或 php:8.2-slim），只 COPY vendor/、autoload.php、应用代码，不 COPY composer.lock 或 .composer 目录
- 确保 builder 阶段执行的是 composer install --no-dev --optimize-autoloader --classmap-authoritative，跳过开发依赖并生成高效加载器
启用 BuildKit + 缓存挂载（推荐）
启用 BuildKit 后，可用 RUN --mount=type=cache 让 Composer 自动复用缓存，无需手动管理 ~/.composer/cache：
- 在 builder 阶段的 RUN 指令前加 # syntax=docker/dockerfile:1 声明新版语法
- 写类似这样的指令：
RUN --mount=type=cache,id=composer-cache,dest=/root/.composer/cache \
composer install --no-dev --optimize-autoloader - BuildKit 会自动跨构建复用该 cache ID，且不会把 cache 目录打进镜像层
避免污染最终镜像的常见坑
即使用了多阶段，稍不注意仍会增大体积：
- 不要在 final 阶段 RUN composer install —— 这会让 composer 下载器、临时 zip 解压文件、未清理的 .git 目录等全留在镜像里
- 不要 COPY . /app 包含 composer.json/lock 在内再 install —— 应先 COPY lock+json，再 install，再 COPY 代码，保证 vendor 层可缓存
- 检查最终镜像是否含 /root/.composer、/tmp/composer*、vendor/bin/*（除非真需要）—— 可在 final 阶段用 RUN rm -rf /root/.composer /tmp/* 清理（但更推荐从源头规避）
验证缓存是否生效的小技巧
构建时加 --progress=plain 查看每层耗时和缓存命中状态；也可在 builder 阶段末尾加：
RUN du -sh /root/.composer/cache && ls -A /root/.composer/cache
观察 cache 目录大小是否稳定增长（说明复用成功），而不是每次从零开始下载。
基本上就这些。重点不是堆命令，而是理解：缓存要挂对位置、安装要精简参数、复制要精准范围。做对这三点，vendor 层基本能稳定在 50–150MB（视项目而定），且构建速度快、镜像干净。
