「为什么每次改一行代码,构建要八分钟?」这是我被问得最多的问题之一。多数时候原因不在编译本身,而在 Dockerfile 的写法让缓存从头失效:先 COPY 全部源码、再 npm install,于是任何一次改动都让依赖层重下重装。另一个方向相反的问题同样常见——镜像从 300MB 涨到 2.1GB,没人说得清多出来的空间是哪一层。
这篇讲两件事:把构建缓存用对,以及把镜像体积砍到该有的样子。所有判断都基于 docker build 的真实输出,不靠猜。
一、先看懂构建输出里的 CACHED 标记
执行 docker build 时每一行末端的 CACHED 是最重要的信息,但很多人默认开了 buildkit 的进度显示之后根本看不到。先把输出模式调成 plain,就能逐行看清哪一步命中、哪一步重新执行。
DOCKER_BUILDKIT=1 docker build --progress=plain -t app:v1 . 2>&1 | grep -E '^#[0-9]+ \[|CACHED|DONE'判断逻辑很简单:命中缓存的行会显示 CACHED,没命中的会显示 DONE 0.3s 之类的耗时。连续看两次构建(一次不改代码,一次只改一个源文件),对比两次的 CACHED 分布,就能立刻定位「缓存断在哪一层」。这一步通常十秒内给出答案,比读文档快得多。
还有一个细节:buildkit 默认用 RUN --mount=type=cache 之外的方式时,RUN 层的缓存键包含指令字符串加上父层的哈希。也就是说父层一变,后面全断。这就是为什么把 COPY 放在安装依赖之前是灾难性的。
二、缓存失效的四个真实原因
按出现频率排序,第一是上面说的层顺序错误。第二是 COPY . . 把 .git、node_modules、日志、本地配置文件一起塞进去——这些文件每次都不一样,等于强制让这一层永不命中。解法是 .dockerignore,而且它必须是「白名单式」的,不能只列几个明显的大目录。
# .dockerignore
.git
node_modules
vendor
*.log
.env*
storage/cache
tests
docs第三是镜像基础标签用了 latest 或者不固定版本号。每次 docker build 时 base image 的 digest 可能已经变了,于是 FROM 层直接失效,后面全部重建。生产构建应该钉到具体版本甚至 digest,比如 php:8.2-fpm-bookworm,定期有意识地升级而不是每次构建随机升级。
第四是构建参数和 secret 处理不当。带 ARG 的层,其缓存键包含参数值。如果你的 CI 里 ARG BUILD_NUMBER 每次都不同,而这一层又在前半部分,那它后面所有层全部失效。这类写法看着无害,实际是最贵的一种——因为构建号、时间戳这种参数完全没有必要进入镜像。
顺带一个第四点五:在 Dockerfile 里 apt-get update 与 apt-get install 分两条 RUN 写,也会导致「install 命中旧缓存而 update 没跑」,最后装出来的包版本对不上甚至 404。永远写成一条 && 串联,并且在同一条里 rm -rf /var/lib/apt/lists/*。
三、把依赖安装拆到独立层:最有效的一次重构
正确的多阶段结构是这样的:先只复制依赖清单文件,装依赖,再复制源码。这样源码改动不会触发依赖重装。区别有多大?以 Node 项目为例,改一行业务代码的构建时间从 6~8 分钟降到 15~30 秒。
FROM node:20-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
FROM node:20-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-bookworm-slim
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
USER node
CMD ["node", "dist/server.js"]这里有三处值得抄的细节。第一,依赖清单是「一组文件」而不是一个,package-lock.json 必须一起 COPY,否则 npm ci 会失败——而且 ci 和 install 的语义不同,前者严格按 lock 装、装不上就报错,后者会偷偷改 lock。构建里一律用 ci。
第二,最后那个运行阶段只 COPY 产物,不要把 node_modules 从 build 阶段整个搬过来——build 阶段装了 devDependencies,那里面有编译工具、测试框架,体积可能是运行时依赖的三倍。
第三,装完依赖之后才 COPY . .,顺序不能反。上面这个例子里 COPY . . 在下一次构建时如果只有 src 变了,npm ci 那一层仍然 CACHED,这是整篇最关键的一行。
四、镜像体积:先量再砍
不要凭感觉猜哪一层大。docker history 会列出每一层的体积,docker image inspect 给出总大小和层数。先把这两个数字拿到,再决定砍哪里。
docker images app:v1 --format '{{.Repository}}:{{.Tag}} {{.Size}}'
docker history --no-trunc --human app:v1 | head -20
docker run --rm app:v1 du -sh /usr/local/lib/node_modules 2>/dev/null常见的体积来源按经验排序:devDependencies 混进运行镜像、apt 缓存没清、编译工具链留在最终镜像、多语言文档和测试数据、以及 Docker 层的「删除不省空间」效应。最后这条最让人困惑:在 A 层 rm -rf 了一个文件,体积不会减少,因为文件的字节还在 A 层里。唯一的办法是让这个文件从一开始就不进入最终镜像,也就是多阶段构建。
实测过一个典型 PHP 站:单阶段构建 1.4GB,改成多阶段(build 阶段装 gcc 和 make 编译扩展,final 阶段只拷 .so)之后 380MB。这 1GB 省下来,在拉取镜像、冷启动、备份传输上都直接兑现成时间。
基础镜像的选择影响也很大,但要算清楚账。Alpine 体积小,代价是 musl libc 与 glibc 的差异,某些预编译二进制(尤其是一些数据库客户端和老旧的 C 扩展)在 Alpine 上装不上,或者性能不同。Debian slim 是折中方案,多几十 MB,换来的是几乎所有官方包都能用。这一点我是吃过亏才改的——早期贪体积全用 Alpine,结果某次升级一个依赖时它在 musl 下直接段错误,排查花了半天。
五、缓存挂载与构建参数:进阶的两个开关
buildkit 支持把包管理器的缓存目录挂进构建过程,它不进入镜像层,但能在多次构建间复用。这对于没有 lock 文件或者需要从源码编译的项目收益明显。
RUN --mount=type=cache,target=/root/.cache/pip \
--mount=type=cache,target=/go/pkg/mod \
pip install -r requirements.txt注意 cache 挂载的语义:它跨构建持久,但不在镜像里。所以它不影响最终产物的可复现性,只影响速度。唯一要小心的是缓存目录里如果混入了「上一次构建留下的产物」,可能导致构建结果依赖历史状态。用 sharing=locked 可以在并发构建时避免互相踩。
另一个开关是 --cache-from 配合 CI。本地构建天然有缓存,但 CI 每次都是干净的机器,默认什么缓存都没有。做法有两种:一是用 registry 缓存(--cache-to type=registry 和 --cache-from type=registry),二是把上一次的镜像拉下来当缓存源。前者更省事,缺点是每次都要推拉缓存层,对自建 registry 的带宽有要求。中小站我倾向后者,逻辑简单、可控。
六、验证构建真的可复现
缓存用对了之后,还要确认一件事:同一个 commit 两次构建出来的镜像是不是同一个。这是「可复现构建」的最低要求,做不到的话,线上问题和本地结果对不上时你就失去了最后一条线索。
docker build -t app:test1 .
docker build --no-cache -t app:test2 .
docker run --rm app:test1 md5sum /app/dist/main.js
docker run --rm app:test2 md5sum /app/dist/main.js两行 md5 一致,说明产物稳定;不一致通常是构建脚本里嵌了时间戳、随机数或者依赖了网络上的浮动版本。这在静态资源指纹(文件名带 hash)的场景下尤其重要——如果每次构建 hash 都变,那客户端的缓存全部失效,性能优化白做。
顺便说一个容易忽略的验证点:拉一次镜像,看层数和体积是否与本地一致。有次我发现 CI 里构建的镜像比本地大 200MB,最后查明是 CI 用的基础镜像标签解析到了不同的架构变体,两个平台的层不一样。所以上面说的「钉死版本号」不只是为了缓存,也是为了这个。
七、这套做法的边界
上面所有优化都基于一个前提:构建是幂等的、只依赖输入文件。如果你的构建过程会去拉外网的浮动资源(比如从某个 CDN 下一个最新的 jQuery)、或者依赖构建机的环境变量,那缓存反而会带来「本地能过、CI 不过」的幻觉。这种情况下第一件事不是优化缓存,而是把这些不确定性收口——把外部资源 vendor 进来,把环境变量显式写成 ARG 并在 CI 里固定。
另一个边界是并发。多台构建机共享 registry 缓存时,缓存的命中率取决于标签策略,往往没有单机那么理想。这时候更实际的做法是「保证大部分层稳定」而不是「追求 100% 命中」,把依赖层做成几乎不变的(钉版本 + lock 文件),剩下的交给 Docker 的增量机制。
最后一句实话:构建速度的收益上限和团队规模相关。一个人维护一两个站,每天构建三五次,把时间从 8 分钟压到 30 秒,一年省下的是几十个小时,足够抵掉学习成本。但如果构建次数很少,那这件事的优先级应该排在「备份能不能恢复」后面。