开发工具 BuildKit 构建缓存 怎样处理

BuildKit 构建缓存怎样处理，关键不是把所有缓存都塞进一个位置，而是先分清三层：Dockerfile 指令产生的层缓存、RUN --mount=type=cache 使用的 builder 本地缓存，以及 CI 通过 --cache-to、--cache-from 传递的远端缓存。前两层解决本机重复构建，最后一层解决临时 CI runner 没有持久磁盘的问题。

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

最稳妥的处理方式是：先把依赖文件和源码分层，再给包管理器/编译器加 cache mount；CI 中使用独立的 registry cache ref 导入和导出，最后用日志与 builder 用量确认到底命中了哪一层。

• 本地构建：优先检查当前 builder 的内部缓存。
• 依赖与编译：使用 RUN --mount=type=cache，但不要把它当成最终镜像内容。
• CI 构建：必须显式配置远端缓存的导入和导出。

先把三层缓存放到正确入口

如果使用 Docker Desktop，先按 Docker Desktop → Builds → Builders → 选择当前 builder → Cache 打开构建器详情。不同版本的面板名称可能略有差异，但要找到的是 builder 详情、缓存占用和构建记录，而不是镜像列表。

命令行可以用下面两条命令做同样的确认。第一条查看当前 builder，第二条查看它实际占用的缓存：

# 查看当前 buildx builder 及其节点状态
docker buildx ls

# 查看 builder 的缓存明细
docker buildx du

图中是操作位置的说明图，不是 Docker Desktop 的真实截图。看到 builder 状态为可用、缓存用量能够列出，才适合继续调整 Dockerfile。

Dockerfile 先分层，再给编译器挂缓存

依赖文件变化频率通常低于业务源码，所以先复制 go.mod、go.sum，再下载依赖；源码变化时，前面的依赖层仍有机会复用。cache mount 存在于 builder 本地存储，不会自动成为最终镜像层，也不会随着远端 --cache-to 一起导出。

# syntax=docker/dockerfile:1
FROM golang:1.25 AS build
WORKDIR /src

# 先复制依赖清单，让源码修改不必重复解析依赖
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go mod download

# 再复制源码，避免业务改动让依赖下载层失效
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -o /out/app ./cmd/app

这里两个目标路径分别对应 Go 模块下载缓存和编译缓存。缓存内容可能被另一次构建覆盖，也可能被 BuildKit 的垃圾回收清空，因此构建必须在空缓存下仍然成功。多个构建同时写入需要独占访问时，再把挂载项设置为 sharing=locked。

把 CI 缓存导入导出写进构建命令

临时 runner 每次都可能换一台机器，本地 cache mount 就会从空目录开始。CI 应该把 Dockerfile 层缓存导出到 registry，并在下一次构建前导入。点击路径可以记成 Builds → 当前构建 → Cache import/Cache export；真正稳定、可复制的配置仍然写在构建命令里：

# 导入主分支已有缓存，并把本次结果回写到当前分支
docker buildx build --push \
  -t registry.example.com/demo/app:ci \
  --cache-from type=registry,ref=registry.example.com/demo/app:buildcache-main \
  --cache-to type=registry,ref=registry.example.com/demo/app:buildcache-feature,mode=max \
  .

--cache-from 负责读，--cache-to 负责写；只写其中一边，缓存链路就不完整。主分支和功能分支最好使用不同的 cache ref，避免并发构建互相覆盖。mode=max 会包含更多中间层，通常更容易让后续构建命中，但导入导出数据也会更多；项目较小时可以先用默认的 min 再比较实际结果。

用状态和日志判断缓存是否真的生效

验收时不要只看第二次构建变快。按下面路径检查：Builders → 当前 builder → Cache usage 查看本地缓存是否增长；在 CI 构建详情中查看是否出现 cache import/export；构建日志中再确认依赖下载和编译步骤是否被复用。

# 只清理超过一天未使用的构建缓存
docker buildx prune --filter until=24h

# 清理前先确认当前 builder，避免误操作其他节点
docker buildx ls

最后记住一个边界：cache mount 是性能辅助，不是依赖的唯一来源；registry cache 也不是镜像发布结果。即使两者都失效，干净 builder 仍应能够重新完成构建。

两个常见疑问

为什么配置了 cache-to，cache mount 仍然是空的？

因为 cache mount 保存在 builder 本地，不属于导出的 build cache。CI 换了新 builder 后，它自然从空目录开始；需要在 runner 上复用持久磁盘，或把依赖下载缓存交给 CI 平台的专用缓存机制。

registry cache 应该和镜像使用同一个标签吗？

不建议混用。镜像标签表达可运行产物，cache ref 表达构建中间层；为主分支、功能分支或不同流水线使用清晰独立的 ref，更容易回滚、清理和排查。