3038 字
15 分钟
Docker 构建加速进阶:缓存挂载、远程缓存与并行构建
2026-11-16

改一行前端代码,推上去,CI 转了十分钟才把镜像构建完——这种等待多半不是机器慢,而是构建姿势不对:依赖每次都从零下载、缓存只存在于某台机器的本地、几个互不相干的阶段排着队串行跑。层缓存的原理和基础用法在 BuildKit 缓存篇 里已经讲过,这一篇不重复,只讲进阶招:让下载的包跨构建复用、让 CI 也吃上缓存、让构建期密钥不留痕、让能并行的阶段一起跑。

先说结论:构建加速的顺序是先定位慢在哪一段,再对症下药,盲目加机器往往没用。

先分清:慢在哪一段#

一次 docker build 的耗时大致分三段,每段的解法完全不同:

阶段慢的表现对应解法
传上下文构建刚开始就卡在 “sending build context”,几十秒没动静.dockerignore 砍掉大目录
装依赖每次都重新 pip install / npm install / apt-get install,流量跑满缓存挂载、依赖层分离
编译与打包CPU 打满,编译型语言尤其明显多阶段并行、远程缓存复用别人的构建结果

先用最粗暴的方法量化一下,知道时间花在哪:

Terminal window
# 冷构建:完全不用缓存
time docker build --no-cache -t myapp:cold .
# 热构建:改一行代码后立刻再构建一次
time docker build -t myapp:hot .
# 看每一层都是谁、多大
docker history myapp:hot

两个时间差得越多,说明缓存越值得折腾;docker history 则能看出哪个层异常肥。下面逐段拆解。

缓存挂载:下载过的包不要再下第二遍#

层缓存有个先天短板:只要某一层的输入变了,这一层和它之后的所有层全部重来。pip install 这种命令最吃亏——requirements.txt 没变还好,一旦加了个包,整层作废,几十个包全部重新下载。

BuildKit 的缓存挂载(cache mount)就是来补这个短板的:把下载缓存目录挂成一个独立于镜像层的持久缓存,构建时挂进来用,构建完卸走,缓存本身不进镜像、不会让镜像变胖,但下次构建还在。

用它之前,Dockerfile 第一行先声明语法版本,这是所有 --mount 玩法的总开关:

# syntax=docker/dockerfile:1

pip:Python 项目#

# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

第一次构建照常下载,但 wheel 全部留在缓存里;之后哪怕 requirements.txt 变了、层缓存失效,pip 也会先翻本地缓存,只下新增的那几个包。

npm:Node 项目#

# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json .
RUN --mount=type=cache,target=/root/.npm \
npm ci
COPY . .
CMD ["node", "server.js"]

apt:系统包#

apt 比较特殊,要挂两个目录,而且得关掉 apt 自带的列表清理、并删掉 Docker 镜像里那个强制清缓存的配置,否则缓存留不住:

# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
&& --mount=type=cache,target=/var/cache/apt,sharing=locked \
--mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
apt-get update \
&& apt-get install -y --no-install-recommends curl git

两个细节:

  • sharing=locked:多个构建并发时排队用同一份缓存。apt 的缓存被并发写容易出问题,官方示例就带 locked;pip、npm 一般可以省略,用默认的 shared。
  • id= 命名:--mount=type=cache,id=myname,target=... 可以给缓存起名字。多个项目共用一台构建机时,用 id 把缓存隔开,避免互相污染;不写 id 时默认按 target 路径区分。

sharing 一共三档,按工具的脾气选:

sharing 取值行为适合场景
shared(默认)多个构建同时读写同一份缓存pip、npm 这类自己带锁或不怕并发写的工具
locked同一时间只允许一个构建用,其余排队等apt,以及任何并发写会损坏缓存的工具
private每个构建用自己独立的一份缓存,互不共享只想保住”有缓存”又怕被别人污染时

选错的代价不对称:该 locked 的用了 shared,可能缓存损坏、构建随机失败;该 shared 的用了 private,只是没吃到共享红利,慢一点而已。拿不准工具脾气时,先按官方示例抄,跑稳了再调。

secret 挂载:构建期密钥别写进镜像#

有些构建步骤必须要密钥:拉私有 npm 源、下载授权字体、调内部 API。最常见的错误写法是把它塞进构建参数:

Terminal window
# 反面教材:千万别这样传密钥
docker build --build-arg NPM_TOKEN=xxxx .
WARNING

用 ARG 传密钥,值会被记进镜像的构建历史,任何人拿到镜像跑一遍 docker history --no-trunc 就能把密钥读出来。ARG 传进的密钥等于明文印在镜像上,镜像推到哪,密钥泄到哪。

正确做法是 secret 挂载:构建时把密钥文件临时挂进构建容器,默认出现在 /run/secrets/<id>,只在那一条 RUN 执行期间存在,不落层、不进历史:

# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json .
RUN --mount=type=secret,id=npm_token \
NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
COPY . .

构建命令对应着给:

Terminal window
docker build --secret id=npm_token,src=./.npm_token -t myapp .

顺带提一句,同类还有 --mount=type=ssh:构建时借用宿主机的 SSH Agent 拉私有 Git 仓库代码,私钥同样不落盘进镜像,写依赖私有仓库的项目时很顺手。

传密钥方式密钥去向安全性
ENV 写死在 Dockerfile镜像配置里明文最差,等于公开
ARG 构建参数记入构建历史,docker history 可读差,镜像分发即泄密
--mount=type=secret只在单条 RUN 期间以文件出现好,不落层不进历史

远程缓存:让 CI 也吃上缓存#

本地构建快不算本事——CI 每次都是全新机器,本地缓存一点用不上,这才是”改一行等十分钟”的主战场。解法是把缓存导出到镜像仓库里,下次构建先从仓库把缓存拉回来:

Terminal window
docker buildx build \
--cache-from type=registry,ref=registry.example.com/myapp:cache \
--cache-to type=registry,ref=registry.example.com/myapp:cache,mode=max \
-t registry.example.com/myapp:latest \
--push .

两个参数分工明确:--cache-from 负责拉,--cache-to 负责推。关键在 mode=max:默认的 mode=min 只导出最终镜像用到的层,中间阶段(比如专门装依赖、做编译的 stage)的缓存不会导出,下次构建还是得重跑;mode=max 把全部中间层都导出去,代价是推拉的缓存体积更大,但 CI 场景下这笔账划算。

它和 buildx 多架构构建 是同一套工具链,命令骨架完全一致,学会一个等于会了两个。在 GitHub Actions 里还有个专用后端 --cache-to type=gha,直接借 Actions 自带的缓存空间、不用自备仓库,只适合它一家的环境,这里不展开,CI 流水线的完整组织见 Docker CI/CD 流水线篇。

依赖层分离:源码改动别连累依赖重装#

这是性价比最高、却最常被写错的一招。反面写法:

# 反面教材:先拷全部源码
COPY . .
RUN pip install -r requirements.txt

COPY . . 之后随便改哪个文件,这一层的摘要就变了,紧跟其后的 pip install 层缓存必然失效——明明依赖一个字没动,也要全部重装。

正确顺序是先只拷依赖清单、装依赖,最后才拷源码:

# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

这样日常改业务代码,只重跑最后那个 COPY 和之后的步骤,装依赖的层稳稳命中缓存。再叠上前面讲的缓存挂载,就算依赖清单真的变了,也只是补下载新增包,双保险。

写法改业务代码后改依赖清单后
先 COPY . . 再装依赖依赖全部重装依赖全部重装
先拷清单装依赖、后拷源码只重拷源码层仅补下载新增包(有缓存挂载时)

Dockerfile 的整体组织规范(基础镜像选择、多阶段瘦身等)见 Dockerfile 编写指南,本篇只聚焦顺序与缓存这一件事。

并行构建:互不依赖的阶段一起跑#

多阶段构建还有一个隐藏福利:互不依赖的 stage,BuildKit 会自动并行构建。比如一个阶段编译前端静态资源、一个阶段编译后端二进制、最后一个阶段只是把两边的产物拷进来组装——前两个阶段没有依赖关系,BuildKit 会同时开跑,吃满多核。

想吃到这个红利,Dockerfile 得把阶段拆干净:每个 stage 只依赖自己真正需要的输入,别把所有事情挤在一个 stage 里串行做完。验证是否并行,看构建输出里多个 stage 是否同时在推进即可。

如果一次构建要出多个镜像(比如同一个仓库的多个服务),用 docker buildx bake 描述一组目标,它会统一调度、并行构建,比写一串 docker build 顺序执行快得多。bake 的完整用法和 CI 集成在 CI/CD 流水线篇里展开,本篇只提醒有这么个工具。

还有一个最容易被忽视的慢源:构建上下文。docker build 开始之前,要先把构建目录打包发给构建器,目录里要是躺着 node_modules、.git、几个 GB 的日志和数据文件,光传输就先慢一步。.dockerignore 写严一点:

.git
node_modules
dist
*.log
data/
.env

上下文瘦身是所有加速手段里成本最低的一个,改几行文本,立竿见影。

排障小节#

缓存挂载没生效,每次还是全量下载。 按顺序查三件事:一是 Dockerfile 第一行有没有 # syntax=docker/dockerfile:1,没有这行声明或版本太老,--mount 直接被忽略或报错;二是 target 路径写没写对,缓存挂的是工具真实使用的缓存目录,pip 是 /root/.cache/pip、npm 是 /root/.npm,写错一位就挂了个空目录;三是构建是不是走了 BuildKit,老版本 Docker 或手动关掉 BuildKit 时 --mount 不被支持。

远程缓存推不上去。 先确认构建机登录过目标仓库(docker login),且这个账号对缓存要推的那个仓库路径有写权限——缓存 ref 本质上也是个镜像 tag,没权限就推不动;其次确认用的是 docker buildx build 且加了 --push 或 --output,普通 docker build 的本地构建不会把 --cache-to 的内容真正送出去,本地驱动对远程缓存的支持也不完整,CI 里建议显式建一个 docker-container 驱动的 builder。

缓存太旧,装到了旧版本的包。 缓存挂载复用的是下载缓存,包管理器的索引(比如 apt 的包列表、pip 的解析结果)过期时,可能解析出旧版本。apt 场景保证每次都执行 apt-get update 且 /var/lib/apt/lists 也在挂载范围内;实在被缓存坑到怀疑人生时,docker buildx prune 清掉 BuildKit 缓存、或者构建时临时不挂缓存跑一次冷构建验证,别在旧缓存上反复猜。注意 docker buildx prune 清的是构建缓存,别和删镜像、删数据卷的命令混用,生产机器上先看清楚清的是什么再回车。

构建还是慢,但三段都查不出问题。 回到开头的方法重新量化:--no-cache 冷构建和热构建各跑一遍计时。如果冷热时间差不多,说明缓存根本没命中,逐层看构建输出里哪一层最先出现 CACHED 消失的位置,那一层就是断点,通常是某个 COPY 把不该变的文件带了进来,或者一条 RUN 前面放了每次都变的构建参数。

小结#

构建加速没有银弹,就是把三段耗时逐个摁下去:.dockerignore 管住上下文,依赖层分离加缓存挂载管住装依赖,多阶段并行和远程缓存管住编译与 CI 复用。secret 挂载顺手把构建期密钥的安全问题一并解决了。改完之后用冷、热两次构建的计时对比验收,数字不会骗人。

Docker 构建加速进阶:缓存挂载、远程缓存与并行构建
https://www.anexns.cloudns.org/posts/docker-build-acceleration/
作者
Anexns
发布于
2026-11-16
许可协议
CC BY-NC-SA 4.0