Go sumdb 为什么下载私有模块时报校验错

Go 下载私有模块时如果报错指向 sum.golang.org、verifying module 或 checksum mismatch，最常见的原因是模块路径没有被标记为私有。Go 默认会从模块代理取得内容，并在缺少本地校验记录时询问公共 checksum database；私有模块若仍走这条路径，就可能出现无法公开查询、仓库内容不可访问或校验记录不匹配。

先为实际的私有模块前缀配置 GOPRIVATE。只有在企业代理仍要承载私有模块时，才进一步拆分 GONOSUMDB 和 GONOPROXY；不要一上来全局设置 GOSUMDB=off。

官方参考：https://go.dev/ref/mod、https://go.dev/wiki/Modules

先判断错误来自 sumdb、代理还是私有仓库

这三个位置的错误文字很像，但修复动作不同。看到 sum.golang.org 或“module lookup disabled”时，优先检查隐私匹配；看到 proxy.golang.org、404 或 410 时，检查代理回退；如果日志已经进入 Git、SSH 或企业代码托管域名，则要检查仓库凭据、权限和模块路径。

# 查看当前 Go 实际采用的模块和网络配置，避免只看 shell 配置文件
go env GOMOD GOPROXY GOPRIVATE GONOSUMDB GONOPROXY GOSUMDB

# 只下载目标模块，便于把错误范围缩小到一个版本和路径
go mod download -json example.com/your-org/private-module

不要把 go.sum 的一行缺失直接判断成“校验错”。缺失记录通常会触发一次可信来源查询；真正的 mismatch 是下载内容的哈希与已有记录不一致，这时应先确认模块版本和来源是否正确。

用 GOPRIVATE 标记真正的私有路径

GOPRIVATE 使用逗号分隔的 glob 模式匹配模块路径前缀。它既是隐私声明，也会默认成为 GONOPROXY 和 GONOSUMDB 的默认值：匹配的模块不走公共代理，也不向公共 checksum database 查询。

# 只匹配公司模块前缀，保留公共依赖的代理和校验保护
go env -w GOPRIVATE=corp.example.com/*

# 多个私有组织使用逗号分隔，不要用 * 误伤全部依赖
go env -w GOPRIVATE=corp.example.com/*,github.com/your-org/*

这里的模式应贴近模块路径，而不是仓库网页地址。例如模块声明为 corp.example.com/payments/sdk，就应让模式覆盖 corp.example.com/。配置完成后再次执行原来的 go mod download；如果错误从 sumdb 转移到 Git 认证，说明隐私边界已经生效，下一步是补齐仓库访问能力。

按职责配置 GOPRIVATE、GONOSUMDB 和 GONOPROXY

企业通常有自己的模块代理。此时不能机械地把所有私有模块都改成 direct，而要明确“私有模块从哪里下载”和“谁提供校验记录”。三个变量可以这样理解：

# 私有代理承载私有模块，公共模块仍可回退到官方代理
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct

# 私有模块不提交给公共 checksum database，但继续由私有代理提供内容
go env -w GONOSUMDB=corp.example.com/*

# 只有明确需要直连版本库时才绕过私有代理
go env -w GONOPROXY=corp.example.com/direct/*

GOSUMDB=off 会扩大关闭范围，意味着所有未在本地记录中的模块都失去公共校验数据库带来的重复下载保护。它可以用于受控的离线环境，但不应作为一个私有模块报错时的默认修复。

配置生效后仍报错，按这个顺序排查

1. 确认模块路径。 查看依赖的 module 声明和 go list -m all 输出，确保模式匹配的是模块前缀，而不是包名的一段。
2. 确认代理状态码。 私有代理返回 404 或 410 时，Go 才会按 GOPROXY 继续回退；认证失败的 401 或 403 通常不会自动当作“换下一个源”。
3. 确认 Git 非交互凭据。 CI 中要让 SSH、令牌或 Git credential helper 已经可用，不能依赖人工输入密码。
4. 确认旧的 go.sum 记录。 如果同一版本曾从错误来源获取，先核对版本、提交和代理内容；不要为掩盖不一致盲目删除整个 go.sum。

# 只检查当前模块的依赖图，不把网络配置改成全局关闭校验
go list -m all

# 检查缓存中已下载模块是否被修改过
go mod verify

最小结论与常见问题

“私有模块时报 sumdb 校验错”的第一修复通常是精确设置 GOPRIVATE。若公司必须使用私有代理，则用 GONOSUMDB 控制公共校验查询，用 GONOPROXY 控制代理选择；最后再处理仓库权限、代理认证和已有 go.sum 记录。这样既能让私有依赖正常下载，也能保留公共依赖的校验保护。

GOPRIVATE 和 GONOSUMDB 可以同时设置吗？

可以，但通常先设置 GOPRIVATE 就足够。只有当代理路径和校验路径需要不同策略时，才显式拆分两个变量。

删除 go.sum 能解决校验错误吗？

不一定。它可能暂时移除旧记录，却不能修复错误的模块路径、代理内容或仓库权限；应先确认下载源和版本，再让 Go 生成所需记录。