必须使用与运行时一致的PHP版本镜像作为builder阶段，显式安装依赖并固定Composer版本，严格按COPY锁文件→RUN install顺序执行，启用BuildKit缓存挂载，且final阶段需保持WORKDIR一致、同步复制autoload.php并修正vendor权限。
直接在 Docker 多阶段构建中集成 Composer，是当前 PHP 应用 CI/CD 流水线提速最有效、最稳定的方式——不是“可以试试”，而是“不这么干就会反复踩坑”。关键不在“会不会写多阶段”，而在 builder 阶段是否真正隔离、参数是否严格、缓存是否可控。
builder 阶段必须用含完整工具链的 PHP 镜像，不能只用 composer:latest
composer:latest 默认绑定最新 PHP（如 PHP 8.3），但你的应用可能要求 PHP 8.1 或 7.4。版本错配会导致 composer install 成功，运行时却报 Class not found 或扩展缺失错误。
- 推荐写法：
FROM php:8.1-cli-bullseye AS composer_build（与 final 阶段 PHP 版本完全一致） - 必须显式安装构建依赖：
RUN apt-get update && apt-get install -y unzip git curl && rm -rf /var/lib/apt/lists/* - 再装 Composer：
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer - 避免用
composer:2这类镜像——它不保证 PHP 小版本兼容，且无法控制扩展（如mbstring、json必须存在，否则--classmap-authoritative会失效）
vendor 层缓存失效的三个典型操作
Docker 层缓存对 composer install 极其敏感，以下任一操作都会让整个 vendor 层重建，拖慢 CI 时间：
-
COPY . /app放在COPY composer.json composer.lock ./之前——导致每次代码变更都触发重装 - 在
COPY composer.json composer.lock ./和RUN composer install之间插入RUN chmod或RUN mkdir——破坏缓存链 - 未固定
COMPOSER_CACHE_DIR，又没启用 BuildKit 缓存挂载，导致每次下载全量包
正确顺序只有这一种：
COPY composer.json composer.lock ./ RUN composer install --no-dev --optimize-autoloader --classmap-authoritative --no-scripts --no-progress
final 阶段 COPY --from=builder 的权限与路径陷阱
常见现象：镜像构建成功，容器启动后报 require(): Failed opening required 'vendor/autoload.php'。问题往往不出在代码，而出在路径或权限。
- 确保 builder 和 final 的
WORKDIR完全一致（如都设为/app），否则COPY --from=builder /app/vendor /app/vendor复制后，autoload.php实际路径和composer dump-autoload生成的 classmap 不匹配 - Alpine 镜像默认以 root 运行，但某些 PHP 扩展（如
pdo_mysql）加载时会检查文件属主；建议 final 阶段加一句：RUN chown -R www-data:www-data /app/vendor - 别漏掉
autoload.php本身——它必须和vendor/同步复制，不能靠运行时生成（--classmap-authoritative已禁用动态查找）
BuildKit 缓存挂载是提速关键，但必须配对使用
启用 BuildKit 后，--mount=type=cache 能复用 Composer 全局缓存，但单靠它还不够。
- 必须在 Dockerfile 开头声明：
# syntax=docker/dockerfile:1 - builder 阶段的 RUN 指令要写成：
RUN --mount=type=cache,id=composer-cache,dest=/root/.composer/cache composer install ... - 同时设置环境变量避免干扰：
ENV COMPOSER_CACHE_DIR=/root/.composer/cache - CI 环境中还要确认构建命令启用了 BuildKit：
DOCKER_BUILDKIT=1 docker build ...，否则--mount会被静默忽略
最终镜像里不会出现 /root/.composer，但 builder 阶段的下载速度会从分钟级降到秒级——前提是 lock 文件没变，且 cache ID 一致。
