RUN指令缓存依赖前一层状态和命令字符串是否变化，任一改变即导致该层及后续所有层缓存失效；应合并相关命令、前置稳定操作、避免隐形变更，并结合多阶段构建隔离高变动任务。

RUN 指令是 Docker 构建中缓存敏感度中等但影响面最广的指令之一。它不直接读取文件内容，但其执行结果和哈希值依赖两个关键因素：前一层状态（即上一指令生成的镜像层）和当前命令字符串本身是否变化。只要这两者任一改变，该 RUN 层就失效，后续所有层缓存连带中断。

合并命令，减少层数量

每条 RUN 都会创建新层，层数越多，缓存链越脆弱。应把逻辑相关的操作合并为单条 RUN，并及时清理中间产物：

• 用 && 连接多条 shell 命令，避免多次启动 shell 进程
• 安装后立即删除包管理器缓存（如 apt 的 /var/lib/apt/lists/*、yum 的 clean all）
• 避免分多行 RUN 安装依赖再清理——那样第二条 RUN 无法复用第一条的环境，且容易因顺序微调导致缓存断裂

前置稳定操作，延缓缓存失效

RUN 的缓存是否命中，取决于它前面所有指令是否都未变。因此要把变动少的操作尽量提前：

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

• 先 RUN 安装基础工具（curl、git、build-essential 等），这些极少修改
• 再 RUN 安装语言依赖（如 pip install -r requirements.txt），前提是 requirements.txt 已通过 COPY 单独复制并置于 RUN 之前
• 避免在 RUN 中直接 COPY 或引用构建上下文中的动态文件（如 RUN curl -O https://.../app.tar.gz && tar xz），这类操作每次都会失效

注意命令字符串的“隐形变更”

Docker 对 RUN 指令的缓存键是完整命令字符串（含空格、换行、注释）。以下看似微小的改动都会导致缓存失效：

• 调整命令内反斜杠续行位置（apt-get install a \ b vs apt-get install a b）
• 添加或删减 shell 注释（# install deps）
• 环境变量展开方式不同（RUN echo $HOME vs RUN echo "$HOME"）
• 使用 exec 格式时参数数组顺序或内容变化（["sh", "-c", "ls"] ≠ ["sh", "-c", "ls -l"]）

配合多阶段构建隔离高变动 RUN

对于编译类任务（如 go build、npm build），频繁修改源码会导致整个构建链重跑。应将其移入 builder 阶段：

• 第一阶段用完整工具链 RUN 编译，输出二进制
• 第二阶段只 COPY 二进制，不再执行任何编译型 RUN
• 这样源码变更完全不影响运行时镜像的构建缓存