改一行前端代码,推上去,CI 转了十分钟才把镜像构建完——这种等待多半不是机器慢,而是构建姿势不对:依赖每次都从零下载、缓存只存在于某台机器的本地、几个互不相干的阶段排着队串行跑。层缓存的原理和基础用法在 BuildKit 缓存篇 里已经讲过,这一篇不重复,只讲进阶招:让下载的包跨构建复用、让 CI 也吃上缓存、让构建期密钥不留痕、让能并行的阶段一起跑。
先说结论:构建加速的顺序是先定位慢在哪一段,再对症下药,盲目加机器往往没用。
先分清:慢在哪一段
一次 docker build 的耗时大致分三段,每段的解法完全不同:
| 阶段 | 慢的表现 | 对应解法 |
|---|---|---|
| 传上下文 | 构建刚开始就卡在 “sending build context”,几十秒没动静 | .dockerignore 砍掉大目录 |
| 装依赖 | 每次都重新 pip install / npm install / apt-get install,流量跑满 | 缓存挂载、依赖层分离 |
| 编译与打包 | CPU 打满,编译型语言尤其明显 | 多阶段并行、远程缓存复用别人的构建结果 |
先用最粗暴的方法量化一下,知道时间花在哪:
# 冷构建:完全不用缓存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:1pip:Python 项目
# syntax=docker/dockerfile:1FROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN --mount=type=cache,target=/root/.cache/pip \ pip install -r requirements.txtCOPY . .CMD ["python", "app.py"]第一次构建照常下载,但 wheel 全部留在缓存里;之后哪怕 requirements.txt 变了、层缓存失效,pip 也会先翻本地缓存,只下新增的那几个包。
npm:Node 项目
# syntax=docker/dockerfile:1FROM node:22-slimWORKDIR /appCOPY package.json package-lock.json .RUN --mount=type=cache,target=/root/.npm \ npm ciCOPY . .CMD ["node", "server.js"]apt:系统包
apt 比较特殊,要挂两个目录,而且得关掉 apt 自带的列表清理、并删掉 Docker 镜像里那个强制清缓存的配置,否则缓存留不住:
# syntax=docker/dockerfile:1FROM debian:bookworm-slimRUN 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。最常见的错误写法是把它塞进构建参数:
# 反面教材:千万别这样传密钥docker build --build-arg NPM_TOKEN=xxxx .WARNING用 ARG 传密钥,值会被记进镜像的构建历史,任何人拿到镜像跑一遍
docker history --no-trunc就能把密钥读出来。ARG 传进的密钥等于明文印在镜像上,镜像推到哪,密钥泄到哪。
正确做法是 secret 挂载:构建时把密钥文件临时挂进构建容器,默认出现在 /run/secrets/<id>,只在那一条 RUN 执行期间存在,不落层、不进历史:
# syntax=docker/dockerfile:1FROM node:22-slimWORKDIR /appCOPY package.json package-lock.json .RUN --mount=type=secret,id=npm_token \ NPM_TOKEN=$(cat /run/secrets/npm_token) npm ciCOPY . .构建命令对应着给:
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 每次都是全新机器,本地缓存一点用不上,这才是”改一行等十分钟”的主战场。解法是把缓存导出到镜像仓库里,下次构建先从仓库把缓存拉回来:
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.txtCOPY . . 之后随便改哪个文件,这一层的摘要就变了,紧跟其后的 pip install 层缓存必然失效——明明依赖一个字没动,也要全部重装。
正确顺序是先只拷依赖清单、装依赖,最后才拷源码:
# syntax=docker/dockerfile:1FROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN --mount=type=cache,target=/root/.cache/pip \ pip install -r requirements.txtCOPY . .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 写严一点:
.gitnode_modulesdist*.logdata/.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 挂载顺手把构建期密钥的安全问题一并解决了。改完之后用冷、热两次构建的计时对比验收,数字不会骗人。