根本原因是 go mod download 层未被缓存——必须将 COPY go.mod go.sum ./ 紧接 RUN go mod download，且中间不能插入其他指令；否则因文件哈希变化导致缓存失效。
Go 项目 Docker 构建慢？根本原因不是网络或机器性能，而是 go mod download 层没被缓存住——只要 go.mod 或 go.sum 一变，后面所有层全失效。
为什么 go mod download 必须单独成层
这一步下载的是模块源码（不是二进制），内容稳定、变更频率极低。Docker 缓存只认指令+输入文件哈希：如果把 COPY . . 放在 RUN go mod download 前面，哪怕只改一行业务代码，. 的哈希就变了，导致 go mod download 这层永远无法复用。
-
COPY go.mod go.sum ./必须紧挨着RUN go mod download，中间不能插其他指令 - 不要用
COPY . .代替精确拷贝，它会把vendor/、tmp/等无关文件带进来，污染缓存哈希 - 若项目用了
replace或本地路径依赖，需确保这些路径在构建上下文中存在且路径一致，否则缓存虽命中但构建失败
多阶段中 builder 阶段的 WORKDIR 和 COPY 顺序不能错
常见错误是先 WORKDIR /app 再 COPY . .，结果 go.mod 被复制到 /app/go.mod，而 go mod download 默认在当前目录执行——没问题；但一旦你加了 -modfile 或切换 GOPATH，路径错位就会触发重下载。
- 标准写法必须是：
WORKDIR /app→COPY go.mod go.sum ./→RUN go mod download→COPY . . -
COPY . .应放在go mod download之后，且前面不能有RUN指令修改工作目录或环境变量 - 如果项目结构是
cmd/myapp/main.go，COPY . .后要确认go build能正确解析导入路径，避免因go.work或GOPATH干扰导致缓存层编译失败
--mount=cache 在 Go 构建中基本无效，别浪费时间配
--mount=type=cache 对 go mod download 几乎没用。Go Modules 的缓存机制（$GOCACHE、$GOPATH/pkg/mod）本身是内容寻址+本地磁盘存储，BuildKit 的 cache mount 无法替代它，反而可能因挂载路径冲突导致模块校验失败。
立即学习“go语言免费学习笔记（深入）”；
-
go mod download产生的pkg/mod数据本就可跨构建复用，前提是基础镜像和 GOPROXY 不变 - 真正该挂载的是
$GOCACHE（用于编译缓存），但多阶段构建中 builder 阶段是临时容器，挂载意义不大 - 如果你硬要用
--mount=type=cache,id=gomod,target=/go/pkg/mod，得确保/go/pkg/mod权限为 0755 且属主为 root，否则go mod download会静默失败
最终镜像里别留 vendor，也别留 go.sum 的“假安全感”
有人以为 go mod vendor + ADD vendor/ 能绕过网络，其实反而破坏缓存：vendor 目录体积大、diff 频繁，一次小更新就让整个 vendor 层失效；而且 go.sum 在 vendor 模式下不参与校验，等于白放。
- 纯 modules 模式（不用 vendor）才是缓存友好方案，
go.mod+go.sum文件小、语义明确、变更可控 - 若必须 vendor，请用
go mod vendor -v生成后COPY vendor ./vendor，并确保go build -mod=vendor显式启用，否则仍会联网 - 最终运行镜像里
go.sum完全不需要——静态二进制不校验依赖哈希，留它只会增大镜像
最易被忽略的点：CI 环境里 go mod download 缓存是否跨 job 复用，取决于你用的是 BuildKit 的 inline 缓存还是 registry 缓存；本地开发时反复 docker build --no-cache 会直接废掉所有层，这不是配置问题，是操作误伤。
