11 月 4 日下午两点,业务仓库只改了一行 COPY,CI 上的构建从 COPY conf 那一步往下全部重跑,二十一分钟才推出镜像,平时七分钟。docker 镜像层本该在第二次构建时被直接取用,plain 日志里那串 CACHED 排到 COPY conf /etc/app/ 就断了。当天要发的版本拖到下班以后,中间还白跑了一次全量构建。
镜像层的缓存键,由指令文本与上下文一起算
构建缓存按指令逐层计算,某一层的键变了,它后面每一层都要重算。
docker 镜像层,指的是镜像里由一条构建指令生成的一份只读文件系统快照,生成之后不再变动,能被后续构建直接取用。它不可就地修改,改动只能叠成新的一层,这条性质把复用的判据压到了键上,与时间先后没有关系。
层只读这件事有一个直接后果,docker history 里列出的行数就是层数,一条 ENV 也算一层。层数越多,键的链条越长,中间任何一环断掉,后面的都要重来。
镜像层的复用其实有两种,落在两个完全不同的地方。pull 的时候看 digest,本地已有同一层就跳过不传;build 的时候看构建缓存的键,键对上了才跳过重算。这次卡住的是后一种,拉镜像是正常的。
BuildKit 给每层算一个键,键里有父层的 ID,有指令原文,也有指令涉及的文件内容校验和。RUN 这类指令没有文件参数,键里只剩前两样,Dockerfile 里改一个空格,这一层就失效。
COPY 与 ADD 要多算一样,被复制路径下每个文件的内容都进校验和,.dockerignore 排除掉的不参与。源写成目录时,目录里每个文件都算数,这一点与「只复制了该复制的东西」的直觉相反。
构建结束后,键与层的对应关系留在构建机的元数据里。下一次构建逐条比对,对上了打 CACHED,对不上就从这一层往下重算,后面的层跟着一起重算,不管后面的指令有没有动过。日志里第一个不叫 CACHED 的指令,就是链断掉的位置。
$ cat Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package.json yarn.lock ./
COPY conf /etc/app/
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build
$ docker build --progress=plain -t web:1104 . 2>&1 | tee build-1104.log
#1 [internal] load build context
#1 transferring context: 486.34MB 2.1s done
#6 [2/6] COPY package.json yarn.lock ./
#6 CACHED
#7 [3/6] COPY conf /etc/app/
#7 DONE 0.2s
#8 [4/6] RUN yarn install --frozen-lockfile
#8 12.47s ...
#9 [5/6] COPY . .
#9 DONE 1.8s
这段日志里只有 COPY package.json yarn.lock 那一步被打上了 CACHED,COPY conf 起就一路重算。它还能命中,是因为它的父层与它自己的指令原文都没动过,再往后的层父层已经换了。
日志里的 [2/6] 是 BuildKit 的步骤编号,与镜像层数不一一对应,[internal] 那一行就不产层。判读时只看前面的指令,不看编号。
日志顶上那行 transferring context: 486.34MB 当时被跳过去了。复盘时最先翻出来的就是这一行,一个前端仓库把上下文传到构建机上要两秒多,这里面有不该进去的东西。
当晚的怀疑先落在缓存上
缓存没有坏,--no-cache 重跑一遍只是把同样的层再算一次,读数不会变。
日志断在 COPY 这一行,第一反应是构建机上的缓存记录读不出来。八月有过一次磁盘写满,构建机重启之后缓存被清过一次,那个旧印象把判断带偏了。
按这个判断动手做了四件事。清 builder 缓存,换一台 runner,把 docker 升到新版本,加 --no-cache 重跑。这四件都没有让日志换一个字,yarn install 照旧从头跑。
$ docker builder prune -af
Total: 1.832GB
$ docker build --no-cache -t web:1104-nocache --progress=plain . 2>&1 | grep -c CACHED
0
$ docker history --no-trunc web:1104 | head -3
IMAGE CREATED BY SIZE
5c1e0d7f41b2 RUN /bin/sh -c yarn build # buildkit 38.2MB
9a04b3c15e77 COPY dir:. /app # buildkit 12.7MB
b73f45e8c902 RUN /bin/sh -c yarn install --frozen-lockfile 412MB
prune 收回了一点八 GB,说明缓存确实存在,占的地方也不小。清掉之后的下一次构建还是二十一分钟,这一条跟「缓存被污染」的假设对不上。
换 runner 那一次的结果最有说服力。新机器上没有本地缓存,构建二十一分钟;老机器上缓存还在,也是二十一分钟。两边读数一样,说明老机器上的缓存从来没有被用上。
--no-cache 那一次的读数与默认参数那次没有区别,两边都是二十一分钟。缓存本来就没有参与进来,谈不到坏不坏。
docker history 里 yarn install 那层的 ID 与上一次构建不同,它是被重新算出来的,不是从一份坏掉的记录里读出来的。
那一行 COPY 同时动了两样东西
这一行既改了层在链上的位置,也把复制范围从一个文件放大成了一个目录。
改之前它写成 COPY conf/app.conf /etc/app/,排在 RUN yarn install 后面。改之后源路径换成整个 conf 目录,整条指令被挪到依赖安装前面。挪位置与换路径是两次动作,当时当成一次做的。
层在链上的位置一变,它后面所有层的父层 ID 就全变了。RUN yarn install 的指令原文一个字没改,父层换了,键跟着换,这一层与它后面的层只能重算。
目录那一半更隐蔽。conf 里多数是长期不变的配置,另有一个 CI 在构建前写进去的 build-info.json,内容是 commit 短哈希与时间戳。
$ ls -l conf
-rw-r--r-- 1 app app 212 Nov 4 13:58 build-info.json
-rw-r--r-- 1 app app 1842 Oct 30 09:12 app.conf
$ cat conf/build-info.json
{"commit":"a41f9c2","built_at":"2026-11-04T13:58:07+08:00"}
$ cat .dockerignore
node_modules
.git
$ du -sh .
486M .
这个文件每次构建都不一样,COPY conf 那一层的校验和每次都不同。即便把位置挪回原处,这一层依然命不中,它一变,后面照旧全量。
.dockerignore 里只有两行,dist 没有排除。上下文里带着上一次的构建产物,COPY . . 那一层也跟着不稳定,每次构建要把将近五百 MB 送到构建机上。
上下文路径写在 docker build 最后一个参数上,CI 里那一行是 docker build -t web .,点号指的是整个仓库根。仓库根以下没有排除的文件都会被打包送过去,COPY 里写什么并不影响这一步。
改法落在源路径与层序上
把 COPY 的源收窄到具体文件,并把变化频率低的层排在前面。
COPY conf/app.conf /etc/app/ 换回单文件写法,需要两个文件就写两条 COPY。.dockerignore 补上 dist,上下文从 486MB 降到 3MB 出头,transferring context 那一步的时间几乎归零。
层序按变化频率排。基础镜像与依赖清单在最前,装依赖跟在它们后面,源码也往后,构建产物压到最后。源码改得最勤,排在最后,它前面的层就不受牵连。
依赖清单只在增删包的时候才变,改一处业务代码碰不到它,这就是把它单独 COPY 出来的全部理由。
$ docker build --progress=plain -t web:1104b . 2>&1 | tail -9
#7 [4/7] RUN yarn install --frozen-lockfile
#7 CACHED
#8 [5/7] COPY . .
#8 DONE 1.6s
#9 [6/7] RUN yarn build
#9 DONE 41.2s
#10 exporting to image
#10 DONE 2.0s
改完第一次构建仍然要全跑一次,从第二次起 yarn install 那层就停在 CACHED,整条构建从二十一分钟落到四分十秒。只改一个源文件再推一次,重算的只有 COPY . . 与 yarn build 两层,读数五十秒上下。
判断的分界
第一处不叫 CACHED 的指令落在哪一类指令上,就往哪一类原因上查,方向比清理动作重要。
落在 FROM 或 RUN apt-get 上,问题在上游标签与镜像源。自己的 Dockerfile 写得再干净也躲不开。
落在 COPY 且源写的是目录,先看目录里有没有每次构建都会变的文件,时间戳与构建号这类东西都算。
整份日志一条 CACHED 都没有,先量上下文。.dockerignore 漏掉产物目录或依赖目录,第一层就要重算。
多阶段构建里还有一层差别。COPY --from=builder 只把产物搬进最终镜像,编译阶段的层不进最终镜像,但构建缓存照样按它们算键,编译阶段的基础镜像一换,后面所有阶段跟着失效。
把这套判据套回这次的事,四十分钟花在清缓存与换 runner 上,真正有效的动作只有两个:把日志里断掉的那一行抄出来,再去看 conf 目录里装了什么。
缓存被污染的排查成本高,出现的概率却远低于一次随手改动的 COPY。改 Dockerfile 的时候把源路径写窄,把变化快的层放到后面,比事后清一次缓存省事得多。