首页 › Docker › Dockerfile 构建（在新窗口打开） › 构建缓存与 .dockerignore

构建缓存机制

Docker 在构建镜像时会缓存每一层。如果某层的指令和上下文没有变化，Docker 直接复用缓存层，大幅加速重复构建。

缓存命中条件

• 指令不变（FROM、RUN、COPY 等）。
• COPY / ADD 的文件内容不变（基于 checksum）。
• RUN 的字符串完全一致。

利用缓存的指令编排

# ❌ 坏实践：先复制所有文件，再安装依赖
# 改一行源码就导致 npm install 重新执行
COPY . .
RUN npm install

# ✅ 好实践：先复制依赖清单，安装依赖，再复制源码
COPY package.json package-lock.json ./
RUN npm install          # 仅当 package.json 变化时才重跑
COPY . .                 # 源码变化不影响上一层缓存

.dockerignore

.dockerignore 文件排除不必要的文件进入构建上下文，减小镜像体积。

# .dockerignore
node_modules
.git
.gitignore
*.md
.env
Dockerfile
.dockerignore
dist
.gitkeep
.vscode
.idea
npm-debug.log*

上下文的概念

docker build -t myapp .

# . 是构建上下文路径，Docker 会将整个目录打包发送给 Docker Daemon
# 一个大上下文会让构建变慢

# 查看上下文大小
docker build -t myapp . 2>&1 | grep "Sending build context"
# Sending build context to Docker daemon  2.048MB

不写 .dockerignore 的后果

# 如果 node_modules 被包含进上下文，发送几百 MB → 构建缓慢
# 如果 .git 被包含，上下文巨大

层缓存失效的常见原因

# 1. ADD 远程 URL 每次都变化
ADD https://example.com/data.tar.gz /data/   # 每次 URL 不变也重新下载

# 2. COPY 整个目录，任何文件变化都导致缓存失效
COPY . .   # 但是已经放在最后一行了，OK

# 3. ARG 变化
ARG VERSION=1.0
RUN echo $VERSION   # 如果构建时传入不同 ARG，此层失效

# 4. RUN 的内容变化
RUN apt install -y curl vim   # 如果指令字符串不同，缓存失效

docker build --no-cache

# 强制重新构建所有层，不使用缓存
docker build --no-cache -t myapp .

# 从特定层开始不使用缓存
docker build --no-cache --target build-stage -t myapp .

多上下文构建

对于以 node_modules 为代表的巨大目录，可以在 .dockerignore 排除后，按需复制：

FROM node:20-alpine
WORKDIR /app

# 在 dockerignore 中排除 node_modules
COPY package.json ./
COPY patches/ ./patches/
# node_modules 在构建时生成，而非复制
RUN npm install

排查缓存问题

# 查看哪些层使用了缓存
docker build -t myapp . | grep "CACHED"

# 查看镜像各层大小
docker history myapp

小结

• Docker 构建缓存基于每层指令和文件 checksum，合理编排指令顺序以最大化缓存命中。
• 将变更不频繁的步骤放前面（安装系统包、安装依赖），变更频繁的步骤放后面（复制源码）。
• .dockerignore 排除 node_modules、.git 等不必要的文件，减小构建上下文。
• COPY 依赖清单 + RUN 安装 → COPY 源码 是标准模式。
• --no-cache 强制重新构建所有层。

上一节：Dockerfile 指令详解 下一节：多阶段构建

贡献者: 布欧-Lewyon