go mod download 下载失败时先看 go_PROXY 和网络连通性
它不走本地 GOPATH，也不自动 fallback 到 direct，失败几乎都卡在这两处。默认 GO_PROXY 是 https://proxy.golang.org,direct，但国内访问前者常超时或被重置，direct 又因模块服务器无认证/限流直接拒绝请求。
- 临时解决：运行
go env -w GO_PROXY=https://goproxy.cn（或https://goproxy.io） - 验证是否生效：执行
go env GO_PROXY，确认输出是你设的地址 - 如果公司内网禁外网，得配
direct+GO_PRIVATE，比如go env -w GO_PRIVATE=git.internal.company.com/* - 别信
go mod download -x的 curl 日志——它只显示 proxy 请求，不显示 direct 失败细节；真要看 direct 行为，加GODEBUG=http2debug=2
go mod download 不会自动更新 go.sum 已有条目
它只下载源码到本地缓存（$GOPATH/pkg/mod/cache/download），不会校验或刷新 go.sum 里已存在的哈希。如果你改过 go.mod 里的版本号，但 go.sum 还留着旧记录，后续 go build 可能报 checksum mismatch。
- 安全做法：改完
go.mod后，跑go mod tidy，它会重新拉取、校验、写入go.sum - 只想预下载不碰
go.sum？可以，但得接受后续构建可能失败——尤其当模块作者重推 tag 或删了 zip 包 -
go mod download all和go mod download ./...行为一致，但前者在 module-aware 模式下更稳定，后者依赖当前目录结构
CI/CD 中用 go mod download 要避开 vendor 冲突
很多人想用它替代 go mod vendor 来“离线构建”，但两者定位完全不同：go mod download 只存源码到全局缓存，不复制进项目；而 vendor 是把依赖打进项目目录。混用会导致构建行为不一致。
- CI 中想提速又保确定性：先
go mod download，再go build -mod=readonly（禁止修改go.mod或go.sum） - 千万别在
vendor存在时还跑go mod download然后删 vendor——go build默认优先读 vendor，缓存下载白做 - 镜像构建中，
go mod download应放在copy go.mod go.sum .之后、COPY . .之前，避免重复下载
go mod download 的 -json 输出对自动化脚本最实用
它不像 go list 那样有丰富字段，但 -json 至少能告诉你每个模块实际下载的版本、校验和、压缩包路径，适合做依赖审计或缓存预热。
立即学习“go语言免费学习笔记（深入）”；
- 示例命令：
go mod download -json github.com/gin-gonic/gin@v1.9.1 - 输出里
Dir是解压后的本地路径，Sum是go.sum该行的哈希值，GoMod是模块的go.mod文件路径 - 注意：
-json不支持通配符，go mod download -json all会报错，必须指定具体模块名 - 如果脚本要批量处理，建议先用
go list -m -f '{{.Path}}@{{.Version}}' all构造参数列表
真正麻烦的不是下载动作本身，而是不同环境对 GO_PROXY、GO_PRIVATE、-mod 模式的隐式依赖；同一行 go mod download 在本地能过，CI 上失败，八成是这三个配置没对齐。