校验和数据库拒绝私有依赖怎么办

如果 go get 或 go mod tidy 报错，提示 Go 正在访问公共校验和数据库，却找不到公司内部模块，先不要把 GOSUMDB=off 当成万能开关。更稳妥的处理是：用 GOPRIVATE 标出私有模块路径，让它默认同时避开公共代理和公共校验和数据库；如果公司有私有代理，再按代理架构补上 GOPROXY 与 GONOSUMDB。

官方资料：https://go.dev/ref/mod#private-modules

先看懂：报错到底卡在哪里

我排查这类问题时，第一眼看模块路径，而不是先改所有 Go 环境变量。假设依赖是 git.corp.example.com/payment/rules，但日志里出现了 sum.golang.org/lookup，通常意味着 Go 没有把这个路径识别为私有模块，于是仍按公共依赖流程请求校验和数据库。

公共模块的校验和可以由公共数据库提供，私有模块则不可能由公共服务计算或确认。GOPRIVATE 是模块路径前缀模式；它默认作为 GONOPROXY 和 GONOSUMDB 的默认值。因此第一版配置通常只需要：

# 用公司模块前缀标记私有范围，避免公开代理和公共校验和数据库
go env -w GOPRIVATE=git.corp.example.com

# 让 Go 读取当前生效的配置，便于确认没有写错层级
go env GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB

这里的关键不是“关闭校验”，而是把私有模块从公共校验和数据库的适用范围中排除。公共依赖仍然可以继续使用 proxy.golang.org 和 sum.golang.org。

第一步：按私有路径配置 GOPRIVATE

如果所有内部模块都以同一个域名开头，可以配置域名前缀；如果只有一部分路径是私有的，就把模式收窄，避免误伤仍希望走公共代理的模块：

# 只把内部 Git 服务下的模块视为私有
go env -w GOPRIVATE=git.corp.example.com

# 多个组织前缀用逗号分隔，不要在值中加入空格
go env -w GOPRIVATE=git.corp.example.com,*.research.example.com

如果公司没有私有 Go proxy，默认的 GOPROXY=https://proxy.golang.org,direct 仍然可以保留：公共模块先走公共代理，私有模块由于命中 GOPRIVATE，会按私有规则直接访问版本控制仓库。直连仓库所需的 Git 凭据仍要由开发机或 CI 提供，GOPRIVATE 不会替你完成授权。

第二步：有私有代理时，不要把两个场景混在一起

企业常见的另一种架构是：私有代理负责内部模块，公共模块仍由公共代理提供。这时可以让 GOPROXY 表达来源顺序，并用 GONOSUMDB 指出哪些模块不应访问公共校验和数据库：

# 私有模块先交给企业代理，公共模块可回退到公共代理
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct

# 私有模块不提交给公共 checksum database
go env -w GONOSUMDB=git.corp.example.com

# 允许私有代理继续承载这些模块，不要用 GOPRIVATE 覆盖掉代理选择
go env -w GOPRIVATE=git.corp.example.com
go env -w GONOPROXY=none

这个组合的判断点是：GONOPROXY=none 让匹配到的私有模块仍可使用 GOPROXY 中的企业代理；GONOSUMDB 则只负责公共校验和数据库这一层。企业代理需要自己具备读取内部仓库的权限，并按 Go proxy 约定正确返回状态码。

如果私有代理只服务内部模块，也可以省略 GONOPROXY，但要确认私有代理对不存在的模块返回 404 或 410，这样 Go 才会按逗号分隔的规则继续回退。代理返回其他错误码时，回退可能停止。

第三步：只在必要时使用 GONOSUMDB 或 GOSUMDB

有些团队仍希望私有模块通过统一代理下载，但不希望公共校验和数据库收到内部路径。这时可以只设置 GONOSUMDB，不要顺手关闭全局校验：

# 只排除公司模块的公共校验和查询，公共模块仍保持校验
go env -w GONOSUMDB=git.corp.example.com

# 只有在明确接受全局失去 checksum database 保障时才使用
# go env -w GOSUMDB=off

GOSUMDB=off 会影响所有未在 go.sum 中已有记录的模块，通常不是“公共数据库拒绝私有依赖”这种局部问题的首选修复。另一个容易混淆的点是：GOINSECURE 允许某些直接下载使用不安全协议，但它不会关闭校验和数据库；不要用它替代 GONOSUMDB。

开发机、CI 和常见误区

本地能下载、CI 仍失败时，重点检查配置是否真正进入 CI 环境，而不是重复执行 go mod tidy。建议把非敏感的路径模式放进 CI 变量，把仓库令牌、SSH key 或凭据交给 CI 的密钥系统；不要把令牌写进 go.mod、go.sum 或文章日志。

还可以按下面的顺序做一次低成本排查：

• 确认私有模块路径与 GOPRIVATE、GONOSUMDB 的模式确实能匹配。
• 确认公司代理是否应该承载私有模块；若应该承载，不要误设让它绕过所有代理的规则。
• 确认 Git 或代理凭据可在非交互 CI 中使用，避免卡在登录提示。
• 公共模块仍有校验和错误时，先检查它是否被错误地纳入私有匹配范围。

速查表：看到什么症状改哪里

常见问题

设置了 GOPRIVATE，还需要手动设置 GONOSUMDB 吗？

通常不需要。GOPRIVATE 默认作为 GONOSUMDB 和 GONOPROXY 的值。只有当代理下载策略与校验和策略不同，才单独覆盖它们。

把 GOPROXY 改成 direct 就能解决吗？

不一定。direct只改变模块来源，不等于把模块标记为私有；如果没有匹配的 GOPRIVATE 或 GONOSUMDB，校验和查询仍可能发生。

总结

这类报错最好按“路径识别—来源选择—校验范围—运行环境”四层处理：没有私有代理时先用 GOPRIVATE；有私有代理时组合 GOPROXY、GONOSUMDB 和必要的 GONOPROXY；不要为一个内部模块问题关闭全局校验。这样既能让私有依赖正常进入构建，也不会牺牲公共模块的可复现下载保障。