改一行代码,docker build 还是从 npm ci 重来:层缓存失效的三个位置
明明只改了一个组件文件,构建还是从装依赖开始重跑。层缓存没坏,是 COPY 的顺序把不该变的东西放在了会变的东西后面。这篇讲 Docker 层缓存的命中条件、COPY 与 .dockerignore 的排序,以及 BuildKit 缓存挂载的用法。
改一个 TS 文件,docker build 还是从依赖安装那一步重来,八分钟起步。层缓存并没有坏,只是你把「不变的」放在了「会变的」后面。
缓存的命中条件比想象中严格
每条指令生成一层,只有同时满足三个条件才复用:指令字符串完全一致、该指令的输入内容哈希一致、父层命中。只要中间断一层,后面全部重建。
RUN 的输入是命令字符串本身,所以哪怕只改了一个空格也会失效。COPY 和 ADD 的输入是被复制文件的内容哈希,这也是绝大多数失效的根源:COPY . . 把整个目录压成一个哈希,任何一处改动都会让这一层之后全部作废。
先排序,再瘦身
正确顺序是:先只拷依赖清单 → 装依赖 → 再拷源码。依赖清单不变,安装层就一直命中。
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
同时把 .dockerignore 补上,node_modules、.git、dist、本地日志、测试快照这些都不该进构建上下文——它们不仅让 COPY 的哈希抖动,还会让上下文上传变慢。
BuildKit 的缓存挂载
包管理器的下载缓存放进 cache mount,不进入镜像层,跨构建复用,这一步对 CI 提速最明显:
# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.npm npm ci
但要注意它只对「下载」有效。node_modules 本身仍然是产物,仍然要写进层里;cache mount 里的内容不会出现在最终镜像中。
CI 上还要显式做缓存导入导出,本地命中不等于流水线命中:
docker buildx build \
--cache-from type=registry,ref=registry.example.com/app:cache \
--cache-to type=registry,ref=registry.example.com/app:cache,mode=max \
-t app:latest .
怎么确认到底哪一层没中
不要靠猜。加 --progress=plain,输出里每条指令前面会标 CACHED 或实际执行;看不到 CACHED 的那一层,就是断点。
docker build --progress=plain -t app:test . 2>&1 | grep -E "^#[0-9]+ \["
docker buildx du --verbose | head -20
第二条看的是本地缓存占用,缓存被 LRU 清掉的概率不低,尤其是磁盘吃紧的开发机。
适用边界与常见坑
- 多阶段构建里,builder 阶段的缓存不会自动传给 runtime 阶段,跨阶段只能靠 COPY --from 传产物。
- .dockerignore 写了排除,但 COPY 的目标目录里已经有旧文件,结果会叠加而不是覆盖,构建出「半新半旧」的镜像。
- 用 COPY 拷 lock 文件时,如果项目里同时存在 package-lock.json 和 pnpm-lock.yaml,只拷其中一个会让缓存判断失真。
- 缓存不是正确性保证:依赖被删除或篡改时,命中缓存会掩盖问题。定期用 --no-cache 做一次全量构建验证。
正在加载评论…