根本原因是COPY . /app一次性复制全部源码导致composer.json或composer.lock变更即失效缓存；应先单独COPY composer.json和composer.lock再执行composer install，最后COPY其余代码，确保vendor层稳定复用。

为什么 composer install 在多阶段构建中经常失效缓存？

根本原因是：Docker 构建时，COPY . /app 会把整个源码（含 composer.json 和 composer.lock）一次性复制进去，而 composer install 命令又依赖这两个文件——只要任一文件有变更（比如改了注释、换行符、dev 依赖开关），Docker 就会认为上一层缓存失效，导致后续所有层（包括 vendor/）全部重建。

如何让 composer install 层独立且稳定？

核心思路是「只在必要时才触发 vendor 重建」，即把 composer.json 和 composer.lock 单独提前 COPY，并在它们不变时复用已安装的 vendor/ 缓存层。

• 先 COPY composer.json composer.lock ./（注意路径结尾的 ./）
• 再运行 composer install --no-dev --no-scripts --prefer-dist --optimize-autoloader
• 最后才 COPY . .（复制其余源码）

这样，只要 composer.json 或 composer.lock 没变，Docker 就能命中 composer install 那一层的缓存，哪怕你改了 src/ 下几十个 PHP 文件也不影响。

多阶段构建中 vendor 如何安全传递到生产镜像？

别直接 COPY --from=builder /app/vendor /app/vendor —— 这样会把 dev 依赖（如 phpunit）也带过去。必须确保 builder 阶段安装的是 production-only 依赖：

• builder 阶段务必加 --no-dev 参数（否则 vendor/ 含 dev 包，体积大、有安全风险）
• 如果项目用了 autoload-dev 或需要生成 classmap，记得在 builder 中补上 --classmap-authoritative（提升运行时性能）
• 最终镜像中，vendor/ 应该只含 composer install --no-dev 的结果，且权限设为不可写（chown -R www-data:www-data /app/vendor && chmod -R u-w /app/vendor）

常见陷阱与绕过方案

有些情况会让上述缓存策略“看起来”失效，实际是其他原因：

• composer.lock 被 IDE 自动重写（如时间戳、哈希顺序变化）→ 提交前运行 composer update --lock 统一格式
• 使用了 platform 配置（如 "php": "8.2"）但构建环境 PHP 版本不一致 → 构建时用 FROM php:8.2-cli 显式指定，避免 Composer 推断出错
• 启用了 COMPOSER_CACHE_DIR 但挂载了本地 volume → 多阶段构建中该变量无效，应直接依赖 Docker 层缓存，而非外部 cache 目录

最易被忽略的一点：不要在 composer install 后执行 rm -rf /root/.composer 类清理操作——它不会节省镜像体积（因为每层只读，删掉的是上层临时数据），反而可能破坏后续层对 vendor/ 的引用一致性。

# php  # js  # json  # docker  # composer  # app  # 为什么  # copy  # ide  # 镜像  # 的是  # 会把  # 改了  # 根本原因  # 复用  # 就会  # 也不  # 就能  # 设为