必须先copy go.mod/go.sum再执行go mod download，否则源码变更会导致依赖层缓存失效；正确顺序可使依赖下载长期命中缓存，仅编译层因代码改动重建，显著提升构建速度。
go mod download 必须在 COPY 项目代码之前执行，否则每次改一行代码都会让依赖层失效。
Docker 构建缓存是逐层生效的，而 go.mod 和 go.sum 变动频率远低于源码。把依赖下载提前到构建早期，才能让后续编译、运行等步骤真正复用缓存。
常见错误现象：
- 每次
docker build都看到go mod download重新拉包，耗时 30 秒以上 -
go mod download成功但容器内go run报错no required module provides package - 本地
go build正常，Docker 内编译失败，提示找不到 vendor 或版本冲突
正确做法：
- 先
COPY go.mod go.sum ./，再RUN go mod download—— 这步会生成/go/pkg/mod缓存层 - 确保
.dockerignore排除vendor/、node_modules/、.git，避免误触缓存失效 - 若项目使用
replace或本地路径依赖（如replace example.com/foo => ./local-foo），必须COPY对应目录，否则go mod download会跳过它
为什么不能直接 COPY . . 后再 go mod download
因为 COPY . . 会把整个项目目录（含频繁变动的 main.go）复制进去，只要文件改了，这一层就失效，后面所有指令（包括 go mod download）都无法命中缓存。
更糟的是，有些团队误以为加了 go mod tidy 就能兜底 —— 它只修正 go.mod，不保证模块实际存在；go mod download 才是真正拉取并解压到 /go/pkg/mod 的动作。
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
多阶段构建中如何传递模块缓存
模块缓存只存在于构建阶段，不会自动带入运行阶段。但你不需要传 —— 运行阶段根本不需 go 工具链或 /go/pkg/mod。
关键点在于：构建阶段的 go mod download 是为了加速 go build，不是为了“运行时依赖”。只要二进制编译成功，模块缓存使命就结束了。
如果你在运行阶段仍需 go 命令（比如调试用的 dev 镜像），那就得用 named volume 挂载 /go/pkg/mod，或用 docker build --cache-from 复用历史镜像的 layer。
CI 场景下模块缓存容易被忽略的细节
CI 环境默认无缓存，docker build 每次都是冷启动。这时仅靠 Dockerfile 顺序不够，必须配合：
- CI 配置中启用
buildkit（DOCKER_BUILDKIT=1），支持更细粒度的 cache mount - 在
RUN go mod download前加--mount=type=cache,target=/go/pkg/mod，显式复用模块缓存 - 避免在 CI 中用
go clean -modcache或清空/go/pkg/mod—— 这会主动破坏缓存
go mod tidy 或 vendor 能替代分层缓存逻辑 —— 它们解决的是依赖一致性，不是构建效率。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
