go mod download 必须紧随 copy go.mod 和 go.sum 之后，才能确保依赖层缓存生效；只要依赖文件未变，该步骤即命中缓存，避免重复下载，大幅提升构建效率。
go mod download 必须放在 COPY go.mod 和 go.sum 之后
这是缓存生效的前提。Docker 构建时只对 COPY 指令复制的文件内容做哈希比对，go.mod 和 go.sum 是唯一能触发 go mod download 层缓存变化的输入。如果直接 COPY . . 再跑 go mod download，只要任意源文件变动，这一步就全量重跑。
正确顺序是：
COPY go.mod go.sum ./RUN go mod downloadCOPY . .RUN go build -o app .
这样只要没改依赖声明，go mod download 层永远命中缓存——哪怕你刚改完 main.go 并立刻重构建。
多阶段构建中 builder 阶段的缓存最可靠
单阶段构建容易因基础镜像更新（比如 golang:1.22 被重新打标）导致整个缓存链失效；而多阶段里，builder 阶段只承担编译职责，其缓存行为更可控。
关键点：
- builder 阶段用固定标签镜像，如
golang:1.22-alpine，别用latest -
go mod download后不要RUN go clean -modcache，那会主动破坏缓存 - 最终运行镜像（如
alpine:latest）和 builder 完全解耦，它的变更不影响依赖下载层
示例片段：
FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN go build -o main . FROM alpine:3.18 COPY --from=builder /app/main /usr/local/bin/app CMD ["app"]
GOOS/GOARCH 变更或 CGO_ENABLED 切换会静默污染缓存
Docker 层缓存不感知 Go 构建参数变化。如果你在本地开发时交替使用 CGO_ENABLED=0 和 CGO_ENABLED=1，或者交叉编译（GOOS=windows），旧缓存可能残留不兼容的 .a 文件，导致链接失败或符号缺失，但错误信息往往不指向缓存问题。
应对方式：
- 在 CI 或共享构建环境里，明确设置构建参数并固化进 Dockerfile，例如：
ENV CGO_ENABLED=0 - 本地调试需切换参数时，加
--no-cache或手动清理：在构建前插入RUN go clean -cache（仅 builder 阶段） - 避免在同一个 builder 阶段混用不同
GOOS/GOARCH的go build命令
私有模块代理切换后必须清 $GOMODCACHE
如果你从 proxy.golang.org 切到自建 GOPROXY（比如 https://goproxy.cn），Docker 缓存层里可能还存着旧代理下载的模块 zip 和解压内容。这些文件路径相同、版本相同，但实际内容可能因代理策略不同而有差异（比如私有模块重定向逻辑），go build 不校验来源一致性，只会照用。
稳妥做法：
- 在
go mod download前加一层清理（仅限首次或代理变更时）：RUN go clean -modcache && go mod download - 或者更轻量：用
go mod verify检查当前缓存是否与go.sum匹配，不匹配再清 - CI 流水线中建议统一配置
GOPROXY环境变量，避免本地和构建环境不一致
真正难察觉的是：缓存看起来“有效”，构建也成功，但运行时 panic —— 因为某个私有模块的 patch 版本被代理跳过了，而缓存里用的却是旧版。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
