Go mod download详解：预下载依赖场景解析

`go mod download` 表面是简单的依赖预下载命令，实则深陷环境配置的“暗坑”：国内网络下默认代理常失效、私有模块需精准配置 `GO_PRIVATE`、`go.sum` 不自动更新易致校验失败、与 `vendor` 混用引发构建不一致，甚至 CI/CD 中因 `GO_PROXY` 或 `-mod` 模式未对齐而本地成功线上失败；掌握代理切换、`go mod tidy` 协同、`-json` 自动化解析及镜像分层最佳实践，才能真正释放其在离线构建、依赖审计和持续集成中的稳定效能。

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 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 上失败，八成是这三个配置没对齐。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Go mod download详解：预下载依赖场景解析》文章吧，也可关注golang学习网公众号了解相关技术文章。