Docker缓存失效主因是层哈希链断裂：COPY放npm install后导致代码变更触发重装；应先COPY package*.json再RUN npm ci；多阶段构建中各阶段缓存独立；CI需--cache-from配合docker pull；ADD、空格、未ignore目录等均会无条件中断缓存。
为什么 Dockerfile 里把 npm install 放在 COPY 之后就失效了缓存？
因为 Docker 构建缓存是按层逐行比对的，一旦某一层的输入内容变了（比如源码文件更新），它和之后所有层都会失效重算。把 COPY . /app 放在 RUN npm install 前面，意味着每次改一行代码，node_modules 都得重装——哪怕 package.json 根本没动。
正确做法是：先单独 COPY package.json 和 package-lock.json，再 RUN 安装，最后 COPY 其余文件。
-
COPY package*.json ./—— 注意通配符写法，兼容yarn.lock或pnpm-lock.yaml -
RUN npm ci --no-audit—— 用ci而非install，确保锁文件一致、跳过 dev 依赖（如不需要） -
COPY . .—— 这步才拷整个项目，不影响前面的缓存
多阶段构建中，如何让 build 阶段的缓存不被 prod 阶段污染？
缓存只在单个构建上下文中生效；但如果你在 FROM node:18 后又写了 FROM nginx:alpine，那前一阶段的缓存不会影响后一阶段——这是好事。真正的问题在于：两个阶段都用了相同基础镜像 + 相同指令顺序，但中间某步因环境变量或构建参数不同导致哈希变化，整段缓存崩掉。
- 避免在
RUN中使用动态时间戳、随机值或未锁定的版本号（例如apt-get update && apt-get install -y curl应拆成两行，且apt-get install指定精确版本） - 构建参数要用
ARG显式声明，并在docker build --build-arg中传入；不要靠ENV或 shell 变量间接注入 - 如果某阶段仅用于编译前端资源，建议用
node:18-alpine而非完整版，减小层体积，也降低因镜像更新意外破坏缓存的概率
docker build --cache-from 在 CI 中为什么经常不生效？
本地缓存是自动继承的，但 CI 环境默认没有历史层。你得手动拉取旧镜像并显式告诉构建器“从哪儿找缓存”。否则 --cache-from 就是个摆设。
- CI 脚本里必须先
docker pull $REGISTRY/$IMAGE:$TAG（哪怕拉不到也要忽略错误） - 构建命令要带
--cache-from $REGISTRY/$IMAGE:$TAG，且最好加上--cache-from $REGISTRY/$IMAGE:latest作为兜底 - 注意镜像名大小写和 tag 规范：Docker 默认把不带 tag 的镜像当
latest，但很多 registry 不允许覆盖latest，导致缓存来源始终为空 - GitHub Actions 或 GitLab CI 中，别忘了开启
docker/setup-qemu-action（跨平台场景）或配置cache_from的 registry 认证，否则拉镜像失败，缓存直接跳过
哪些操作会无条件中断缓存链？
不是所有指令都参与缓存计算。有些行为会让后续所有层立刻失效，而且不报错、不提示，只能靠经验排查。
-
ADD指令解压 tar 包时会强制刷新缓存（即使 tar 内容没变），一律改用COPY -
RUN后接反斜杠换行，但某行末尾多了空格，会导致该行哈希变化 → 整条链断裂 - 使用
.dockerignore但漏写了node_modules或dist，导致 COPY 实际传入了不该有的大目录，缓存层体积暴涨且极易变动 - 在
WORKDIR后执行RUN cd /app && npm run build——cd不改变工作路径状态，Docker 不识别，实际仍在根目录执行，可能因路径错误触发重试或失败，间接破坏缓存稳定性
缓存不是开关，是哈希链；断一环，后面全重来。最常被忽略的是文件时间戳和隐藏文件（比如 .git 目录是否被 ignore），它们不动声色地让每一层哈希都变。
