复用Composer镜像层的关键是让composer install层跳过而非换镜像；常见缓存失效原因包括：COPY .在COPY composer.json/composer.lock之前、中间插入RUN指令、builder与final阶段PHP环境不一致（如扩展缺失）、未启用BuildKit cache mount，以及COPY路径或权限不匹配。
复用 Composer 镜像层的关键不是“换镜像”，而是让 composer install 这一层在绝大多数构建中完全跳过——只要 composer.json 和 composer.lock 没变，Docker 就不该重跑安装。
为什么 vendor 层总被重建？常见破坏缓存链的操作
缓存失效往往发生在你没意识到的地方。Docker 层缓存是线性的：一旦某层输入变了（文件内容、指令顺序、基础镜像变更），它和之后所有层都会失效。对 Composer 来说，最常踩的坑有：
-
COPY . /app放在COPY composer.json composer.lock ./之前——哪怕只改了一行代码，composer.lock还没 copy 进来，composer install就被迫重跑 - 在
COPY composer.json composer.lock ./和RUN composer install之间插入任意RUN（比如RUN chmod -R 755 /app）——这新增了一层，彻底切断了缓存链 - builder 阶段用了
php:8.2-cli，final 阶段却用php:8.2-fpm-slim，表面版本一致，但slim镜像缺少zip扩展，导致 builder 阶段的composer install实际行为不同（例如 fallback 到 git clone），生成的vendor/结构不一致，缓存形同虚设
必须显式控制 builder 阶段的 PHP 环境一致性
很多人以为“都是 php:8.2”就够了，但实际运行时扩展缺失、ini 设置差异（如 memory_limit）、甚至 unzip 是否存在，都会让 composer install 的输出不稳定，进而让缓存无法复用。正确做法是：
- builder 和 final 阶段使用**完全相同的小版本+发行版**，例如都用
php:8.2-cli-bullseye和php:8.2-apache-bullseye，而非混用bullseye与slim - 显式安装运行时必需的扩展：
RUN docker-php-ext-install mbstring zip pcntl，别依赖镜像默认 - 调大内存限制：
RUN php -d memory_limit=-1 /usr/bin/composer install --no-dev --optimize-autoloader --classmap-authoritative，避免因内存不足触发降级逻辑 - 确认
composer.lock已提交且未被本地composer update意外修改——CI 流水线应校验git status --porcelain composer.lock是否为空
BuildKit 缓存挂载不是可选项，是复用前提
仅靠 Docker 层缓存，只能避免“锁文件不变时重装”，但无法跨构建复用已下载的包。真正提升 CI 速度的是 BuildKit 的 cache mount。必须做三件事：
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
- 全局启用：
export DOCKER_BUILDKIT=1（写入~/.bashrc或 CI 脚本开头） - Dockerfile 开头加：
# syntax=docker/dockerfile:1 - 在 builder 阶段的
RUN前挂载缓存：RUN --mount=type=cache,id=composer-cache,dest=/root/.composer/cache composer install --no-dev --optimize-autoloader
这样，即使你换了机器、清了本地镜像，只要 id=composer-cache 相同，BuildKit 就会自动复用之前下载过的 zip 包和解压产物，composer install 秒出结果。
COPY --from=builder 的路径和权限必须精确匹配
缓存复用成功，不代表运行时一定正常。最终镜像里 vendor/autoload.php 找不到，90% 是因为路径错位或权限问题：
- 确保 builder 和 final 阶段的
WORKDIR完全一致，比如都是/app；否则COPY --from=builder /app/vendor /app/vendor复制后，autoload.php的物理路径和composer dump-autoload生成的 classmap 中记录的路径不匹配 - final 阶段不要用
COPY --from=builder /app /app—— 这会把composer.json、.git、临时文件全塞进去；只复制明确需要的：COPY --from=builder /app/vendor /app/vendor和COPY --from=builder /app/src /app/src - 如果 final 阶段切换了用户（如
USER www-data），需提前确保/app及其子目录对目标用户可读：RUN chown -R www-data:www-data /app，否则require 'vendor/autoload.php'会因权限拒绝失败
真正难的不是写对第一遍，而是当团队成员在不同环境触发构建、CI 使用不同 runner、或者某次更新了基础镜像小版本时，还能让 vendor 层稳定复用——这要求 builder 阶段的环境声明、扩展安装、缓存挂载全部显式、固化、可验证。
