缓存链断裂点出现在首个未显示“Using cache”的构建步骤及后续所有步骤；最常见原因是COPY/ADD指令输入内容变化导致哈希失效，需检查.dockerignore、避免COPY . .、固定依赖版本并排除动态文件。
构建缓存未命中，关键不是看“哪一层没缓存”，而是看“哪一层断开了缓存链”——docker 会从基础镜像开始逐层比对，一旦某条指令的输入（命令文本、文件内容、环境变量）与本地缓存中对应层不一致，后续所有层都会强制重建。日志里最直接的线索，就是哪一步开始没了 using cache。
盯住构建日志里的“CACHED”标记
Docker 构建时默认显示每步是否复用缓存。重点关注输出中是否出现：
- → Using cache：该层命中，跳过执行，直接复用
- → Cache miss 或完全没这行提示：该层未命中，将重新执行（如 RUN、COPY 等）
- → Found cached layer（BuildKit 模式）：等效于 Using cache
缓存链断裂点一定出现在第一个没出现 “Using cache” 的步骤，以及它之后的所有步骤。例如：
COPY package.json . → Using cache<br>RUN yarn install → Using cache<br>COPY src/ ./src → Cache miss<br>RUN npm run build → Cache miss
说明问题出在 COPY src/ 这一步：要么 src/ 目录内容变了，要么构建上下文里有新增/删除文件触发了哈希变更。
检查 COPY/ADD 指令的输入是否稳定
这是缓存失效最常见原因。Docker 对 COPY/ADD 的缓存判定基于文件内容的 SHA256 哈希，哪怕只改了一个空格或时间戳，哈希就变，缓存即失效。
- 确认你没有把
node_modules、.git、logs/、dist/等动态目录打包进构建上下文（.dockerignore 要写全） - 避免在 Dockerfile 里写
COPY . .—— 它会把整个当前目录（含临时文件）都纳入哈希计算 - 检查是否误传了带时间戳的文件，比如自动生成的
build-timestamp.txt或带随机数的配置
验证 RUN 指令是否引入不确定性
有些 RUN 命令看似固定，实则结果不可复现，导致缓存无法复用：
-
RUN apt-get update && apt-get install -y curl：update 每次拉取的包列表可能不同，建议拆成两步，或用固定源 + --no-install-recommends -
RUN pip install -r requirements.txt：若 requirements.txt 含requests>=2.25这类宽松版本，安装结果可能随时间变化；应使用 pinned 版本（如requests==2.28.1）和--no-deps配合 lock 文件 -
RUN date > /app/timestamp：每次构建时间不同，必然失效
对比两次构建的上下文哈希（高级定位）
如果你启用 BuildKit（推荐），可开启详细调试获取更精准信息：
- 运行：
DOCKER_BUILDKIT=1 docker build --progress=plain --no-cache=false . - 观察输出中类似
sha256:abc123... (cache from local)的提示，比对两次构建中同一层的哈希值是否一致 - 若哈希不同，说明输入已变；若哈希相同但未命中，则可能是构建环境差异（如不同平台、不同 Docker 版本）
也可用 docker buildx bake --print 查看构建定义的完整上下文摘要，辅助判断变动来源。
