Docker buildx 缓存导出减少重复构建时间

Docker buildx 的内部缓存默认跟随当前 BuildKit 构建器；CI 任务换节点或构建器被重建后，这部分缓存往往无法继续使用。解决方法是用 --cache-to 把缓存显式导出到 registry、local、inline 或 gha 后端，再在下一次构建中通过 --cache-from 导入。

官方缓存后端文档：https://docs.docker.com/build/cache/backends/

本文以 registry 缓存为主例，因为它适合跨 CI 节点复用；本地开发机也可以把 type 换成 local。配置完成后，不要只凭一次构建的总耗时判断效果，而应到 Docker Desktop 的 Builds > Build history > 选中构建 > Info > Build timing 查看 Cache usage，并与 History 中的相近构建对照。

第 1 步：选择缓存后端和作用域

先确定缓存要在哪里复用。Docker 文档列出的常用后端包括 inline、registry、local 和 gha。外部缓存需要显式导出，也需要在后续构建显式导入；它不是只写一个 --cache-to 就自动生效。

本文使用两个独立引用：正式镜像写入 ghcr.io/acme/demo:latest，缓存写入 ghcr.io/acme/demo:buildcache。这里的 acme 只是占位符，实际使用时替换为自己的仓库命名空间。不要让两个并发分支反复写同一个缓存位置；需要分支级缓存时，为不同分支设置不同 ref，并额外导入 main 分支缓存。

第 2 步：确认当前 Builder 能力

打开 Docker Desktop，依次进入 Settings > Builders。在 Selected builder 区域确认当前构建器名称、Driver、Status 和 Platforms。使用 docker-container 驱动时，可以把 BuildKit 生命周期与默认 Docker 引擎构建器分开管理，registry cache 也更容易形成稳定配置。

确认状态为 Running 后，再在非交互命令环境检查并启动构建器。若还没有独立构建器，可以创建一次；已存在时直接 inspect，避免重复创建同名实例。

# 创建并选中 docker-container 驱动的构建器；只需执行一次
docker buildx create --name cache-builder --driver docker-container --use

# 启动构建器并查看驱动、节点与支持平台
docker buildx inspect --bootstrap

成功状态是 inspect 能列出当前 Builder、Driver、节点状态与支持平台；Docker Desktop 的 Settings > Builders 中也能看到相同构建器被选中。默认 docker 驱动能否使用外部缓存后端还取决于 containerd image store 配置，因此遇到“不支持 cache exporter”时，应先确认驱动能力，而不是删除 Dockerfile 缓存。

第 3 步：首次构建导出 registry 缓存

首次构建没有远程缓存可读，重点是把本次产生的层导出到独立 cache ref。registry 后端支持 mode=min 和 mode=max：min 只导出最终镜像相关层，体积较小；max 还包含多阶段构建的中间层，更容易在复杂 Dockerfile 中获得命中，但导入导出的数据也更多。

# 首次构建正式镜像，并把多阶段缓存导出到独立 registry 引用
docker buildx build \
  --builder cache-builder \
  --push \
  --tag ghcr.io/acme/demo:latest \
  --cache-to type=registry,ref=ghcr.io/acme/demo:buildcache,mode=max \
  .

执行前先通过仓库提供的安全登录方式取得推送权限。不要把 Token 写进 Dockerfile、ARG 或构建上下文；Docker 官方建议构建秘密使用专用 --secret 机制，避免凭据进入缓存层。首次构建完成后，目标仓库应同时存在正式镜像引用和独立缓存引用。

第 4 步：后续构建同时导入并回写缓存

第二次及后续构建需要同时出现 --cache-from 与 --cache-to。前者在构建开始时提供候选缓存，后者把本次的新结果回写。只导入不回写会让缓存停留在旧状态，只导出不导入则无法减少当前构建中的重复步骤。

# 后续构建先导入旧缓存，再把新缓存回写到同一作用域
docker buildx build \
  --builder cache-builder \
  --push \
  --tag ghcr.io/acme/demo:latest \
  --cache-from type=registry,ref=ghcr.io/acme/demo:buildcache \
  --cache-to type=registry,ref=ghcr.io/acme/demo:buildcache,mode=max \
  .

本机单节点测试可以改为 local：

# 从持久目录导入缓存，并在构建结束后更新该目录
docker buildx build \
  --builder cache-builder \
  --load \
  --tag demo:local \
  --cache-from type=local,src=.buildx-cache \
  --cache-to type=local,dest=.buildx-cache,mode=max \
  .

local 目录不要加入镜像构建上下文，建议写入 .dockerignore；CI 中还要确保目录所在卷会跨任务保留。若缓存目录每次都在任务结束后删除，配置虽然正确，下一次仍没有可导入内容。

第 5 步：在 Docker Desktop Builds 视图验收

完成两次内容相同或变化很小的构建后，打开 Docker Desktop 左侧 Builds，进入 Build history，选择状态为 Completed 的目标构建。详情页默认打开 Info，在 Build timing 中查看 Cache usage、各类构建操作和结果导出所占时间。

接着切换到 History，查看相关构建的趋势图与 Past builds。验收时关注三件事：

• 未修改的依赖安装层是否显示为缓存命中。
• 只修改业务源码后，是否仅重建 COPY 之后的必要层。
• 结果导出和缓存导出是否成为新的主要耗时，需要在 mode=min 与 mode=max 间权衡。

如果构建来自 CI，可以使用构建记录文件导入 Docker Desktop，再在 Builds 视图检查。界面中的 Cache usage 是确认缓存利用的依据之一，但不同节点网络、仓库响应和上下文大小也会影响总耗时，因此不要把单次时长差直接等同于缓存效果。

第 6 步：处理缓存未命中与覆盖

配置了 cache-from 仍然没有命中时，按以下顺序排查：

1. 确认缓存确实存在：cache ref 拼写、仓库命名空间和认证权限必须与导出时一致。
2. 确认平台一致：不同目标平台、构建参数或基础镜像摘要可能对应不同缓存记录。
3. 检查 Dockerfile 层顺序：频繁变化的 COPY 放得太早，会让后续依赖安装层一起失效。
4. 检查作用域覆盖：多个分支并发写同一个 ref，可能覆盖此前缓存；应按分支拆分位置。
5. 比较 min 与 max：多阶段构建需要中间阶段时，mode=max 通常覆盖更多层，但传输与存储成本更高。
6. 排除人为禁用：--no-cache 或 --no-cache-filter 会主动跳过相应缓存。

一个常见的分支策略是先导入当前分支缓存，再导入 main 缓存作为后备，而只把新结果导出到当前分支 ref。Docker BuildKit 允许重复指定多个 --cache-from，因此无需把所有分支挤进同一个可写位置。

# 优先读取当前分支缓存，再用 main 缓存补充；只回写当前分支
docker buildx build \
  --push --tag ghcr.io/acme/demo:feature \
  --cache-from type=registry,ref=ghcr.io/acme/demo:cache-feature \
  --cache-from type=registry,ref=ghcr.io/acme/demo:cache-main \
  --cache-to type=registry,ref=ghcr.io/acme/demo:cache-feature,mode=max \
  .

常见问题

为什么第一次构建没有变快？

第一次构建主要是在生成并导出缓存，本来就没有旧的外部缓存可复用。应在输入相同或只发生局部变化的后续构建中观察命中情况。

registry 缓存能和正式镜像使用同一个 ref 吗？

不建议。官方 registry cache 文档要求缓存引用与正式输出位置分开。使用独立的 buildcache 标签或独立仓库，更容易管理生命周期并避免互相覆盖。

mode=max 一定更快吗？

不一定。它导出的中间层更多，可能提高复杂多阶段构建的命中，但也增加上传、下载和存储成本。应结合 Builds 视图中的 Cache usage 与导出耗时选择。

缓存里可以放密钥吗？

不可以。不要用 COPY 或 ARG 传递凭据，使用 BuildKit 的 --secret 或 --ssh，并确保 Dockerfile 不把敏感内容写入层。

官方资料

缓存后端：https://docs.docker.com/build/cache/backends/；buildx build 参数：https://docs.docker.com/reference/cli/docker/buildx/build/；Docker Desktop Builds 视图：https://docs.docker.com/desktop/use-desktop/builds/。

把缓存导出看成构建流水线的持久化接口，关键就清楚了：首次构建负责写，后续构建必须先读再写，作用域不能互相覆盖，最后通过 Builds 视图检查真实命中。这样才能减少可避免的重复构建，而不是只多出一个缓存文件。