Go 下载依赖卡在 sum.golang.org 时怎么处理

我第一次遇到 go mod tidy 卡住 sum.golang.org 时，直觉是把 GOPROXY 换掉；后来发现模块其实已经下载到代理边界，真正卡住的是校验数据库。Go 模块下载至少有两个边界：GOPROXY 负责找到并下载模块，GOSUMDB 负责为尚未出现在 go.sum 的内容取得校验记录。排障时把这两个边界拆开，通常比反复换镜像更快。

公共模块是校验数据库超时，优先调整可达的代理或校验数据库地址；私有模块误发到公共服务，则配置 GOPRIVATE 或 GONOSUMDB。只有明确接受失去全局校验保障的代价时，才考虑 GOSUMDB=off。

先判断到底卡在代理还是校验数据库

先把当前配置打印出来，重点看 GOPROXY、GOSUMDB、GOPRIVATE 和 GONOSUMDB。错误中如果出现 proxy.golang.org 或内网代理地址，通常是下载边界；如果模块已经找到，随后请求 sum.golang.org 超时，则是校验边界。

# 只查看 Go 当前采用的模块网络配置，不修改项目文件
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GONOPROXY

# 用一个明确的模块下载动作观察错误落在哪个服务
go mod download -x example.com/your/module@v1.2.3

官方默认的 GOPROXY 通常包含公共模块镜像并允许在特定状态码下回退到 direct。它解决的是“从哪里拿模块”，并不等于已经完成校验。

公共模块：先修正 GOPROXY 或 GOSUMDB 的可达性

如果公司网络不能直接访问公共校验服务，但允许访问一个能代理模块和校验请求的内网服务，可以把内网地址放在 GOPROXY 中。若只是公共校验数据库地址在当前网络不可达，可按组织网络策略设置一个可用的 GOSUMDB，不要把随机镜像地址写进项目提交文件。

# 示例：让 Go 先使用组织代理，再按代理约定处理公共模块
# 这里的域名只是占位符，实际值应由组织维护者提供
go env -w GOPROXY=https://proxy.corp.example,https://proxy.golang.org,direct

# 若组织提供兼容的校验数据库，再设置其名称、密钥或地址
# 不要把未确认的公共服务地址直接写入仓库
go env -w GOSUMDB=sum.golang.org

代理返回 404 或 410 时，Go 才会继续尝试后面的代理或 direct；其他错误码可能代表代理明确拒绝请求，盲目增加更多地址并不能解决根因。配置完成后，可以用 go env GOPROXY GOSUMDB 检查持久化结果，再重新执行原命令。

私有模块：把隐私边界和代理边界分开

私有模块最常见的误区是只设置 GOPROXY=direct，却忘记告诉 Go 哪些路径不应发送到公共代理或公共校验数据库。GOPRIVATE 会为匹配的模块路径提供默认的私有判断，并影响 GONOPROXY 与 GONOSUMDB；若组织需要更细的控制，再单独设置后两个变量。

# 让 corp.example.com 下的模块按私有模块处理
# 通配模式应覆盖真实的模块路径前缀
go env -w GOPRIVATE=corp.example.com

# 仅在代理策略与校验策略不同的时候拆开配置
go env -w GONOSUMDB=corp.example.com
go env -w GONOPROXY=corp.example.com

# 查看最终生效的值，避免只改了当前 shell 的临时变量
go env GOPRIVATE GONOSUMDB GONOPROXY

如果采用内网代理统一服务公共和私有模块，通常让私有路径仍经内网代理，同时用 GONOSUMDB 阻止公共校验数据库接收私有路径。若直接访问私有代码仓库，则需要准备好非交互式 Git 凭据，避免 Go 在构建时等待输入。

不要用 GOSUMDB=off 掩盖三类不同问题

GOSUMDB=off 会关闭校验数据库查询，但它不能修复模块代理找不到版本、私有仓库无权限或 go.mod 中路径写错的问题。对公共模块，它还会放弃对未记录内容的全局一致性校验；对私有模块，通常更窄的 GOPRIVATE 或 GONOSUMDB 更符合边界。

常见问题

为什么改了 GOPROXY 仍然访问 sum.golang.org？

因为模块代理和校验数据库是两个配置面。代理负责提供模块内容，Go 仍可能为不在 go.sum 中的内容访问校验数据库。需要同时检查 GOSUMDB，或者让代理提供组织认可的校验服务。

什么时候可以临时设置 GOSUMDB=off？

只有在隔离环境、已有可信依赖来源并明确承担校验能力下降的情况下才考虑。更常见的修复是解决出口、代理或私有模块匹配，而不是把全局校验直接关掉。

小结

遇到 sum.golang.org 卡住时，先看请求落在下载边界还是校验边界，再按公共模块、私有模块和内网代理三种场景选择配置。记住：GOPROXY 管下载来源，GOSUMDB 管校验数据库，GOPRIVATE 与 GONOSUMDB 管隐私边界，变量职责分开，排障才不会越改越乱。