go mod download 必须提前执行，否则 go build 会因缺失模块报错退出；ci/cd 和新克隆项目需预先运行该命令，配合 goproxy=https://goproxy.cn,direct 及缓存持久化才能确保高效复用。
go mod download 要提前跑，别等 build 时才触发
Go 不会在 go build 时“顺便”下载缺失模块——它会卡住、报错、退出。真正触发下载的是 go mod download 或首次 go build 中遇到未缓存的模块。但此时下载是阻塞的，且无法并行预热。
- CI/CD 流水线里，在构建前加一步：
go mod download，确保所有依赖进$GOPATH/pkg/mod - 本地开发时，新 clone 项目后立刻执行：
go mod download -x（加-x可看到实际 curl 请求，确认走的是代理而非直连） - 如果
go.mod里有私有模块，direct必须出现在GOPROXY配置末尾，否则会被代理拦截导致 404
GOPROXY 必须配对使用，单设 proxy 不够
只设 GOPROXY=https://goproxy.cn 是危险的：私有域名（如 git.internal.company）会被代理拒绝，报 module not found 或 404。Go 要求 fallback 机制。
- 正确写法：
go env -w GOPROXY=https://goproxy.cn,direct——逗号分隔，direct表示“代理查不到就自己连” - 验证是否生效：
go env GOPROXY输出应含direct；再试go list -m github.com/golang/example，无网络日志即命中缓存 - 国内环境慎用
https://proxy.golang.org，DNS 污染常见，直接超时，不是配置问题
缓存目录要持久化，尤其在容器或 CI 中
$GOPATH/pkg/mod 是模块缓存主目录，但默认挂载在临时文件系统上。Docker 构建或 GitHub Actions 默认每次都是空目录，等于每次都重下。
- Dockerfile 中，把
/root/go/pkg/mod单独作为 volume 缓存：RUN --mount=type=cache,target=/root/go/pkg/mod go mod download - GitHub Actions 用
actions/cache@v4缓存~/go/pkg/mod，key 建议包含go.version和go.sum-hash，避免跨版本污染 - 本地多项目共用同一
GOPATH时，pkg/mod自动复用；不要为每个项目新建独立 GOPATH，反而破坏共享
go clean -modcache 不是日常操作，而是故障恢复手段
缓存损坏的表现通常是 checksum mismatch、invalid version 或反复下载同一模块。这时清缓存才有效。日常开发中频繁执行 go clean -modcache 只会让下次构建变慢。
- 真正该定期做的，是检查
$GOPATH/pkg/mod大小：du -sh $GOPATH/pkg/mod，超过 5GB 且长期不清理，可能积压大量旧版本 - 想精准删旧版？别手动 rm，用
go mod graph | awk '{print $1}' | sort -u | xargs -I{} sh -c 'go mod download {}@latest'预热常用版本，再清其余 - CI 中建议每周定时 job 执行一次
go clean -modcache+go mod download，而不是每次 PR 都清
go build -v，输出里没有 downloading 行，才是真缓存生效。别信配置写了就完事。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
