docker构建缓存失效本质是缓存链过早中断，需从构建上下文、指令顺序、环境一致性三方面排查：观察日志中“using cache”标记定位首处cache miss，检查基础镜像tag漂移、package.json哈希变化、.dockerignore缺失、动态arg或未锁定from标签等问题，并优先启用buildkit与远程缓存提升稳定性。
构建缓存失效导致频繁全量编译，本质是 docker 逐层比对机制被意外触发，使本可复用的中间层全部重建。问题不在“没缓存”，而在“缓存链断得过早”。排查要从构建上下文、指令顺序、环境一致性三方面切入，解决需兼顾即时止血和长期分层治理。
看构建日志：确认哪一层开始失效
运行 docker build 时加 -v 或观察输出中的 Using cache 标记：
- 如果 FROM 行就显示 Downloading 或 pulling，说明基础镜像 tag 漂移（如用了
node:latest）或本地缺失该层 - 若 COPY package.json 后的 RUN npm install 没命中缓存，检查
package.json文件内容是否真没变——Git 中换行符、BOM 头、注释增删都会改变哈希值 - 一旦某层标为 Cache miss，其后所有层必然重建，无需再往下看
查构建上下文：揪出隐藏的变更源
很多失效不是代码改了，而是构建时带入了不该有的文件或时间戳：
- 运行 docker build . -f Dockerfile --no-cache 对比耗时：若差异不大，说明原本就没缓存可用，重点在上下文控制
- 检查 .dockerignore 是否排除了
.git、node_modules、dist、logs等目录——未忽略会导致整个上下文哈希变化 - CI 环境中注意时间戳：某些打包脚本会动态写入
build-time字段或生成临时文件，哪怕不 COPY，也会污染上下文哈希
验指令顺序与参数：避免低级但致命的错配
Docker 缓存匹配严格依赖指令字面值和执行环境一致性：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
-
COPY 必须拆开：先
COPY package*.json .，再RUN npm ci，最后COPY . .。把源码和依赖混在一个 COPY 里，每次改一行 JS 就重装所有依赖 -
ARG 值必须稳定：避免
--build-arg BUILD_TIME=$(date)这类动态参数；如需扰动缓存，用固定标识如--build-arg CACHE_VERSION=20260925 -
基础镜像 tag 要锁定：用
node:18.19.0-alpine替代node:18-alpine，防止上游小版本更新导致 FROM 层失效
用 BuildKit 提升稳定性：从机制上减少误失效
启用 BuildKit 后，缓存判断更精准，还能隔离构建副作用：
- 设置
export DOCKER_BUILDKIT=1，再运行docker build - 用
RUN --mount=type=cache,target=/root/.npm挂载 npm 缓存，避免每次重下包 - 结合远程缓存（
--cache-to type=registry），让不同机器、不同流水线共享同一套构建层，大幅降低首次构建成本
不复杂但容易忽略
