Docker BuildKit cache mount 怎样加速依赖安装

Dockerfile 里的依赖安装经常是重复构建的慢点：源码改了一行，安装步骤重新执行，包管理器又要检查并下载一遍依赖。RUN --mount=type=cache 可以给这个步骤挂载一个由 BuildKit 管理的持久缓存目录。即使当前层需要重新执行，未变化的包仍有机会直接从缓存取出。

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

准备依赖清单和构建入口

先把依赖清单放在源码复制之前。这样只有依赖声明变化时，安装步骤才需要重新计算；日常修改业务源码时，可以尽量复用前面的层。下面以 Go 项目为例，go.mod 和 go.sum 是依赖输入，业务源码则放到后面。

FROM golang:1.25 AS build

# 先复制依赖清单，减少源码改动带来的安装层失效
WORKDIR /src
COPY go.mod go.sum ./

# 下载模块；下载目录会由后面的 cache mount 提供
RUN 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

构建命令使用 BuildKit 路径即可，例如：

# 使用 buildx 构建并给镜像命名
docker buildx build --load -t demo-cache-mount:local .

# 如果环境只有 docker build，也可以显式打开 BuildKit
DOCKER_BUILDKIT=1 docker build -t demo-cache-mount:local .

这里的 --load 只是把结果加载到本地镜像存储；它不负责保存 cache mount。缓存由当前 BuildKit 构建器管理，二者是不同的对象。

为包管理器选择真正的缓存目录

cache mount 最容易写错的地方是 target。目录必须和工具的缓存约定一致，否则构建虽然成功，却只是挂载了一个没有被使用的空目录。常见目录可以这样对照：

不要把项目源码目录当成依赖缓存目录。源码应该通过 COPY 或绑定挂载进入构建步骤，缓存挂载只服务于可以跨构建复用的包、索引或编译中间结果。

把 cache mount 写进 Dockerfile

在需要重复安装或编译的 RUN 指令上添加 --mount=type=cache。Go 项目常见的是同时挂载模块缓存和编译缓存；npm、pip 则分别挂载各自的包缓存。

FROM node:22 AS web-build
WORKDIR /app

# 先复制锁文件，让依赖安装层和业务源码解耦
COPY package.json package-lock.json ./

# npm 缓存只用于加速下载，node_modules 仍由安装命令生成
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# 最后复制经常变化的源码并打包
COPY . .
RUN npm run build

如果使用 Apt，官方建议给 Apt 的缓存目录设置锁式共享，避免并发构建同时修改同一份索引或包缓存：

FROM debian:bookworm-slim

# Apt 的缓存文件可能被并发构建修改，因此使用 locked 共享策略
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*

sharing=locked 的作用是让竞争同一缓存的构建等待，而不是同时写入。它不是所有包管理器的通用必填项；是否需要锁式共享，要看工具对缓存目录的并发访问要求。

构建后核对缓存复用状态

第一次构建通常会填充缓存，后续构建才有机会复用它。核对时不要只看镜像层是否命中：如果源码变化导致安装层重新执行，cache mount 仍可能让未变化的包免于重新下载。可见的成功状态是安装命令仍执行，但下载量明显减少，构建输出显示对应的缓存目录已经被复用。

下面这张原创界面说明图把两个状态并排展示：首次构建写入缓存，再次构建命中缓存。它表达的是静态概念关系，不是某次本机运行的结果。

如果每次都像全新下载，按下面顺序排查：

1. 确认使用的是 BuildKit 或 buildx，而不是忽略 RUN --mount 的旧构建路径。
2. 确认 target 与当前镜像内包管理器的实际缓存目录一致。
3. 确认两次构建使用同一个 builder；切换 builder 后，原来的内部缓存不一定存在。
4. 确认没有在每次构建前主动清理 builder 缓存，也没有把缓存目录指向一次性临时位置。

处理失效和安全边界

cache mount 不是最终镜像的依赖打包方式。它只在构建步骤运行期间提供缓存目录，最终镜像是否包含依赖，仍由安装命令写入的工作目录和多阶段复制规则决定。不要把缓存目录当作运行时数据目录，也不要把密钥、私有仓库凭据或包含敏感信息的文件放进普通 cache mount。

本地构建器长期存在时，内部缓存通常已经足够。CI 使用短生命周期构建器时，可以把构建缓存导出到外部位置，再在下一次构建时导入：

# 将 BuildKit 缓存推送到团队可访问的镜像仓库
docker buildx build \
  --cache-to type=registry,ref=example/app:buildcache,mode=max \
  --tag example/app:latest \
  --push .

# 后续构建从同一个外部缓存读取，减少临时构建器的冷启动成本
docker buildx build \
  --cache-from type=registry,ref=example/app:buildcache \
  --tag example/app:latest \
  --push .

外部缓存解决的是“构建器换了以后缓存还在不在”，不是替代 cache mount。前者保存 BuildKit 的构建缓存，后者把包管理器的可复用目录挂进某个 RUN 步骤，二者可以配合使用。

常见问题

cache mount 会把依赖缓存打进镜像吗？

不会。挂载目录是构建步骤使用的缓存位置；最终镜像只包含命令写入镜像文件系统的内容。若依赖要进入运行镜像，应通过正常安装和多阶段复制显式安排。

为什么 target 写了却没有加速？

最常见原因是目录写错、构建器换了，或者工具实际使用了另一个用户的缓存路径。先查包管理器的缓存配置，再确认两次构建使用同一 builder。

所有 cache mount 都要加 sharing=locked 吗？

不需要。Apt 的索引和包缓存有并发写入要求时适合使用 sharing=locked；其他工具应按其缓存实现选择默认共享、私有共享或锁式共享。

本地有效，CI 里却每次重新下载怎么办？

检查 CI 是否每次创建新的 builder。如果是短生命周期构建器，给 docker buildx build 配置匹配的 --cache-to 和 --cache-from，并确保引用的外部缓存位置在后续任务中可访问。

把 cache mount 用好的关键不是给每个目录都加挂载，而是先找准包管理器真正写入的缓存路径，再让依赖清单与源码分层。这样即使安装层需要重新执行，也能复用未变化的包；当构建器会被替换时，再用外部缓存延续这份收益。