改一行代码,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 做一次全量构建验证。
查看「容器与编排」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

改一行代码,docker build 还是从 npm ci 重来:层缓存失效的三个位置 - 起航社区