Build cache 怎样复用多阶段缓存

如果一个 Dockerfile 同时有依赖安装、源码编译和运行时三个阶段，想让下一次构建继续复用前一次的中间层，关键不是只给最终镜像打标签，而是把 Build cache 单独导出，并在下一次构建时显式导入。最实用的做法是：先把变化少的锁文件放在源码复制之前，再用 --cache-to type=registry 写入独立缓存引用，用 --cache-from type=registry 读取它。

Docker Build cache 官方地址：https://docs.docker.com/build/cache/

多阶段缓存复用可以记成三件事：Dockerfile 顺序决定哪些层容易命中，mode=max 决定是否包含中间阶段，--cache-from 决定下一次构建是否真的把外部缓存接进来。缓存命中后，构建输出通常会显示 CACHED，但这不是最终镜像已经发布的证明。

先把多阶段 Dockerfile 排成容易命中的顺序

先准备一个典型的前端多阶段构建。依赖文件变化频率低，应该单独复制并安装；业务源码变化频率高，放到依赖层之后。这样只修改 src 时，依赖安装层仍有机会直接复用。

# 使用 BuildKit 语法，让 RUN --mount=type=cache 可用
# syntax=docker/dockerfile:1

FROM node:22-alpine AS deps
WORKDIR /app

# 先复制锁文件，避免源码小改动让 npm ci 这一层失效
COPY package.json package-lock.json ./
RUN --mount=type=cache,id=npm-cache,target=/root/.npm npm ci

FROM deps AS build

# 依赖已经准备好，再复制变化更频繁的业务源码
COPY . .
RUN npm run build

FROM nginx:alpine AS runtime

# 运行时只接收构建产物，不把 node_modules 带进最终镜像
COPY --from=build /app/dist /usr/share/nginx/html

这里有两个容易混淆的缓存：Docker 指令层缓存负责复用 COPY、RUN 等步骤；RUN --mount=type=cache 是包管理器的持久目录，用来减少重新下载。后者保存在 builder 本地，不会自动随着 --cache-to 一起导出到 registry，所以不能把它当成跨机器缓存的替代品。

把多阶段缓存导出到独立 registry 引用

在有镜像仓库的环境中，建议把最终镜像和缓存镜像分开命名。下面的 registry.example.com/team/web 只是占位地址，请替换成已经登录且有权限写入的仓库。

# 用同一个 cache ref 导出和导入，避免缓存散落到不同位置
docker buildx build \
  --push \
  --tag registry.example.com/team/web:main \
  --cache-to type=registry,ref=registry.example.com/team/web:buildcache,mode=max \
  --cache-from type=registry,ref=registry.example.com/team/web:buildcache \
  .

--cache-to 指定写入位置，--cache-from 指定读取位置；两者缺一不可。mode=max 会把多阶段构建中的中间步骤也纳入缓存，适合依赖安装和编译阶段较多的 Dockerfile。默认的 mode=min 更小，但只覆盖最终输出所需的层，下一次构建对中间阶段的命中可能不够。

如果使用 inline，缓存会嵌在最终镜像里，配置很简单，但 Docker 官方文档明确提示它对复杂多阶段构建的扩展性不如独立的 registry cache。本文的目标是复用多阶段中间层，因此把缓存放在独立引用里更容易管理。

在下一次构建中导入同一个缓存

本地重复构建时，只要仍然使用同一个 builder 和缓存引用，命令可以继续沿用上面的写法。CI 中要特别注意：运行器通常是临时机器，不能依赖 builder 的本地目录，必须在每次构建命令中显式写 --cache-from。

# 这是 CI 步骤的写法示意，缓存地址应与发布权限和分支策略匹配
- name: Build image with reusable cache
  run: |
    # 先读取主分支或当前分支已有的构建缓存
    docker buildx build \
      --push \
      --tag registry.example.com/team/web:${GIT_SHA} \
      --cache-from type=registry,ref=registry.example.com/team/web:buildcache \
      --cache-to type=registry,ref=registry.example.com/team/web:buildcache,mode=max \
      .

缓存引用被多个并发构建共同写入时，要为不同分支规划不同的 ref，或者接受后写入者覆盖同一缓存位置。Docker 官方文档提醒，一个位置不能被当作多个独立缓存长期同时写入；想同时利用主分支和当前分支，可以使用两个不同的缓存引用分别导入。

从构建输出核对缓存是否复用

为了看到更完整的状态，可以把进度输出改成纯文本：

# 让构建日志保留每个阶段的缓存状态，便于在 CI 中归档
docker buildx build \
  --progress=plain \
  --tag local/web:check \
  --cache-from type=registry,ref=registry.example.com/team/web:buildcache \
  .

核对时看三类信号：

• 出现 importing cache manifest，说明构建器尝试读取了外部缓存引用；
• 依赖安装或早期阶段显示 CACHED，说明 Dockerfile 中对应指令和依赖输入仍满足命中条件；
• 源码复制之后重新执行是正常现象，因为 COPY 输入改变后，后续层也会按依赖关系失效。

不要只看最后一行的构建成功，也不要把一次未命中直接归因于 registry 故障。先比较缓存引用是否一致，再检查锁文件是否被改动、构建上下文是否扩大，以及是否换了 builder 或基础镜像。

多阶段缓存不命中时先查这几个边界

最后归档三项信息就够了：Dockerfile 中缓存边界的顺序、使用的 cache ref、构建日志中命中的阶段。以后换仓库或分支时，先迁移这三项，再调整具体的镜像标签，排查会比盲目添加 --no-cache 更快。

结论与常见问题

复用多阶段 Build cache 的最小闭环是：依赖文件先复制、源码后复制；用 registry backend 导出缓存；下一次构建显式导入；用 --progress=plain 查看 CACHED 和 cache manifest。多阶段项目优先考虑 mode=max，而 RUN --mount=type=cache 只解决 builder 本地的包下载复用，两者职责不同。

为什么最终镜像能复用，但 build 阶段仍然很慢？

常见原因是只导出了最终结果相关层，或导出时使用了 mode=min。把缓存写入独立 registry ref 并使用 mode=max，再在下一次构建中通过同一个 ref 导入，才更容易命中中间阶段。

cache-from 和 cache-to 可以使用不同的引用吗？

可以。它们分别代表读取和写入位置，但如果希望形成连续复用链，通常让写入和下一次读取指向同一个缓存引用；多分支并发时则可以按分支拆分 ref，再按需导入主分支和当前分支缓存。

为什么不能把 cache mount 当成 CI 的远程缓存？

cache mount 保存在 builder 的本地存储，外部 cache backend 不会自动把它恢复到另一台机器。它适合减少同一 builder 的包下载；跨 CI 运行器复用多阶段构建层，则仍要配置 registry 等外部缓存。

相关官方资料：https://docs.docker.com/build/cache/backends/、https://docs.docker.com/build/cache/optimize/、https://docs.docker.com/get-started/docker-concepts/building-images/multi-stage-builds/。