根本原因是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/ 的引用一致性。
