构建缓存怎么分析构建日志排查未命中原因-Docker-PHP中文网

缓存链断裂点出现在首个未显示“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：每次构建时间不同，必然失效