缓存失效由层哈希比对规则严格决定：任一层输入变更（如空格、日志文件、基础镜像更新）即导致该层及后续全量重建；需用.dockerignore排除干扰文件、分层copy依赖与源码、固定基础镜像tag和依赖版本，并避免指令字面差异。
缓存失效不是随机发生的，它严格遵循 docker 的层哈希比对规则。只要某一层的输入变了，这一层及之后所有层都会重建——哪怕只改了一个空格、一个日志文件，或基础镜像悄悄更新了。
构建上下文里混进了不该有的文件
Docker 构建时会把整个上下文目录打包上传，哪怕你只在 COPY 指令里写了 COPY ./src ./app，只要上下文里有 node_modules、.git、tmp/ 或 app.log 这类动态文件，它们的变动就会改变上下文哈希，导致从第一层开始全量重建。
- 在项目根目录下添加
.dockerignore文件，明确排除干扰项 - 典型内容示例：# .dockerignore
node_modules
.git
*.log
tmp/
npm-debug.log - 用
tar -c -f context.tar --exclude-ignore=.dockerignore -C . .手动打包验证实际上传内容
COPY 指令位置和范围不合理
把源码和依赖文件一起复制（比如 COPY . /app），等于把最易变的部分放在最前面。一旦某个测试文件或注释改动，依赖安装层就再也无法复用。
- 拆开复制：先
COPY package.json package-lock.json ./，再RUN npm ci，最后才COPY ./src ./app/src - 避免通配符盲目复制，如不用
COPY . .，改用精确路径列表 - 对 Go 项目，优先
COPY go.mod go.sum ./；对 Python，先COPY requirements.txt ./
基础镜像或依赖版本不固定
FROM ubuntu:latest 或 RUN apt-get install nginx 看似简洁，实则埋雷。上游镜像更新或包管理器拉取新版本，都会让 FROM 层或 RUN 层哈希失效，牵连后续全部重建。
- 基础镜像用具体摘要或带版本号的 tag，例如
FROM ubuntu:22.04@sha256:abc123...或FROM node:18.17.0-alpine - 安装依赖时锁定版本：
RUN apt-get install -y curl=7.81.0-1ubuntu1.18或RUN pip install flask==2.3.3 - 多阶段构建中，各阶段的基础镜像保持一致标签，避免因拉取时间不同导致层 ID 不同
指令顺序或参数引入隐式变更
Docker 缓存比对是字面级的：空格、换行、ARG 值、甚至构建命令里的路径写法差异，都会被识别为新指令。
- 不要随意调整 Dockerfile 指令顺序，尤其是 COPY 和 RUN 的相对位置
- 慎用
--build-arg，若必须用，确保 CI 中每次传入相同值；临时扰动可用ARG CACHE_BUST=1配合脚本生成唯一值 - 避免在 RUN 指令中嵌入动态命令，例如
RUN echo $(date)或RUN git rev-parse HEAD，这类操作必然破坏缓存
