Atopos

1. 缓存的来源：镜像分层

上一篇文章讲过，Docker 镜像由多个只读层组成，COPY、RUN 等指令每次执行都可能产生文件系统变更。Docker 在构建镜像时，会按照 Dockerfile 从上到下的顺序逐一执行每条指令，并检查：当前这个构建步骤的输入和结果，是否和之前某次构建完全一样？ 如果一样，就直接复用之前的结果，跳过实际的执行过程。这就是 Build Cache。

为了方便理解，本文把 Dockerfile 中每条可能产生缓存的指令称为一个”构建步骤”或”缓存节点”——注意，构建日志中显示的步骤编号与最终镜像的文件系统层数量并不总是严格一一对应（比如 WORKDIR、ENV 等指令通常只记录元数据而不产生文件系统层），但在讨论缓存行为时，按步骤来理解是完全够用的。

举个例子，一个标准的 Node.js Dockerfile：

1
FROM node:22           # 步骤 1: 基础镜像
2
WORKDIR /app           # 步骤 2: 工作目录
3
COPY package.json ./   # 步骤 3: 依赖描述文件
4
RUN pnpm install       # 步骤 4: 安装依赖
5
COPY . .               # 步骤 5: 业务代码
6
RUN pnpm build         # 步骤 6: 构建产物

如果两次构建之间 package.json 没有任何变化，那么步骤 1 到步骤 4 都可以直接复用缓存，只有步骤 5 和步骤 6 需要重新执行。反过来，如果 package.json 发生了变化，那么从步骤 3 开始往后的所有步骤都需要重新构建。

2. 缓存如何判断命中

Docker 判断一个步骤能不能复用，不是靠”智能分析”，而是靠比较输入：对于 COPY 指令，Docker 会比较被复制文件的内容（校验和）是否发生变化；对于 RUN 指令，Docker 会比较命令字符串本身是否改变，同时还会综合该步骤之前的构建状态、挂载（mount）和构建参数（--build-arg）等相关输入。 如果指令和所有相关输入都没有变，缓存就命中；变了，缓存就失效。

不过有一个重要的细节需要注意：Docker 不会自动检查 RUN 指令访问的远程资源是否更新。 比如 RUN apt-get update，即使软件仓库中的包版本已经变化，只要缓存仍然有效（命令字符串没变、前面的构建步骤没变），Docker 就可能继续复用之前的结果，而不会主动去拉取最新的软件包索引。这在需要确保依赖为最新版本的生产构建中需要特别留意——必要时可以使用 --no-cache 或在命令中显式打破缓存。

1. 链式依赖规则

Build Cache 最重要的规则只有一条：一旦某一层失效，它后面的所有层都必须重新执行。 因为后面的每一层都以前一层的输出为基础——前一层变了，后续层的”地基”就不同了，即使后续层的指令本身没有改，也不能直接用以前的缓存。

这就是为什么把 COPY . . 放在 RUN pnpm install 前面是一个非常糟糕的做法：

1
# ❌ 糟糕的写法
2
COPY . .
3
RUN pnpm install

这样一来，你改一行日志代码 → COPY . . 检测到文件变化失效 → RUN pnpm install 也必须重新执行 → 每次构建都重装几百个依赖包，即使依赖本身完全没变。

2. 正确写法：稳定内容在前，变化内容在后

正确的做法是把不容易变的内容放前面，容易变的内容放后面：

1
# ✅ 好的写法
2
COPY package.json pnpm-lock.yaml ./
3
RUN pnpm install --frozen-lockfile
4
COPY . .
5
RUN pnpm build

package.json 和 pnpm-lock.yaml 只在添加或更新依赖时才会变化，平时非常稳定。把它们单独复制并安装依赖放在前面，意味着日常的业务代码修改最多只会让最后两层失效——依赖安装那一步永远命中缓存。构建时间从每次几分钟缩短到十几秒，就是靠这一条简单的顺序调整。

3. .dockerignore 保护缓存

有一个容易被忽略的细节：COPY . . 会复制构建上下文中的所有文件，包括那些跟构建根本无关的内容——node_modules、.git、.env、日志文件、测试覆盖率报告等等。这些文件一旦发生变化（比如跑了测试生成了新的 coverage 报告），也会导致 COPY . . 的缓存失效。

.dockerignore 就是为了解决这个问题：

1
node_modules
2
.git
3
.env
4
dist
5
coverage
6
*.log
7
# 如果构建过程不需要文档类文件，再考虑排除
8
# README.md
9
# docs/

告诉 Docker 这些文件不要进入构建上下文，它们的变化就不会影响缓存。但需要注意，.dockerignore 的配置要根据项目的实际情况来定——比如有些项目会在构建时使用 README、将其打进 npm 包、或者在 monorepo 工具链中被读取，这时就不能一概而论地把它排除。一个典型的例子：你更新了 README，如果它不在 .dockerignore 中，每次改 README 都会导致 COPY . . 的缓存失效；如果你的构建过程确实不需要 README，排除它可以避免无意义的缓存失效。

1. 利用 BuildKit 缓存挂载

除了 Dockerfile 层面的缓存优化，BuildKit（Docker 新一代构建引擎，现代 Docker 默认启用）还提供了更精细的缓存控制。以 pnpm 为例，它的包存储（store）默认在 ~/.local/share/pnpm/store，每次 pnpm install 都要从网络下载包——即使同一个包在不同的项目间反复安装。

BuildKit 的 --mount=type=cache 可以把这个目录挂载为持久缓存。需要注意的是，pnpm store 的实际路径可能受环境变量和 pnpm 版本影响，更稳妥的做法是显式指定 store 目录：

1
ENV PNPM_HOME="/pnpm"
2
ENV PATH="$PNPM_HOME:$PATH"
3

4
RUN corepack enable
5

6
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
7
    pnpm config set store-dir /pnpm/store \
8
    && pnpm install --frozen-lockfile

通过 pnpm config set store-dir 显式指定 store 路径，再让 BuildKit 的 cache mount 挂载同一个路径，可以确保 pnpm 和 BuildKit 操作的是同一个目录。如果你能确认镜像中 pnpm 的默认 store 路径，也可以简化写法，但核心原则不变：target 必须与当前镜像中 pnpm 实际使用的 store 路径一致。

2. 查看缓存是否生效

构建时如果看到步骤输出中有 CACHED 标记，说明该步骤使用了缓存。如果想确认缓存是否真的在工作，可以用 docker build --no-cache . 来完全禁用缓存重新构建一次，对比两种构建的耗时差异。

1. 优化前

1
FROM node:22
2
WORKDIR /app
3
COPY . .
4
RUN pnpm install
5
RUN pnpm build
6
CMD ["pnpm", "start"]

问题：每次修改代码 → COPY . . 失效 → pnpm install 重新执行 → 每次构建都要跑完所有步骤，即使你只改了一个字符串。

2. 优化后

1
FROM node:22
2
WORKDIR /app
3
ENV PNPM_HOME="/pnpm"
4
ENV PATH="$PNPM_HOME:$PATH"
5
COPY package.json pnpm-lock.yaml ./
6
RUN corepack enable
7
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
8
    pnpm config set store-dir /pnpm/store \
9
    && pnpm install --frozen-lockfile
10
COPY . .
11
RUN pnpm build
12
CMD ["pnpm", "start"]

效果：修改业务代码 → COPY package.json 和 pnpm install 仍然命中缓存 → 只重新执行 COPY . . 和 pnpm build。每次构建节省的时间取决于依赖数量——依赖越多，效果越明显。

对比图