Go / 系统课时
看懂 go.sum 为什么存在
看懂 go.sum 为什么存在
go.sum 解决的是“同一个模块版本以后还能不能拿到同一份内容”。Go 下载依赖时会对模块文件计算校验和,并把可信结果记录下来;后续机器、CI 或重新下载时再次比对,发现内容变化就停止使用,而不是悄悄继续构建。
学习目标
- 读懂
go.sum每一行的模块路径、版本和h1校验值。 - 区分
go.mod的版本选择职责与go.sum的内容校验职责。 - 用
go get、go mod tidy和go mod verify生成、整理并检查校验记录。
一行 go.sum 到底记录了什么
go.sum 每行有三个字段:模块路径、版本、哈希。版本带 /go.mod 时,只校验该版本的 go.mod;不带后缀时,校验模块 ZIP 中按 Go 规则规范化后的文件内容。当前常见的 h1: 表示 Go 使用的第一版哈希格式。
可以用一个固定版本直接观察。下面示例会创建临时模块并加入 rsc.io/quote v1.5.2;首次执行需要能访问模块源或代理。
mkdir gosum-demo
cd gosum-demo
go mod init example.com/gosumdemo
go get rsc.io/quote@v1.5.2
grep 'rsc.io/quote v1.5.2' go.sum预期结果(首次下载时可能额外出现 go: downloading ... 提示):
rsc.io/quote v1.5.2 h1:3fEykkD9k7lYzXqCYrwGAf7iNhbk4yCjHmKBN9td4L0=
rsc.io/quote v1.5.2/go.mod h1:LzX7hefJvL54yjefDEDHNONDjII0t9xZLPXsUe+TKr0=同一个版本出现两行并不重复:一行约束模块源码内容,另一行约束它的 go.mod。实际项目还会出现间接依赖,所以 go.sum 的模块数量通常比 go.mod 里手写的直接依赖更多。
下载时如何完成校验
公开模块的典型路径是:Go 先从 GOPROXY 指定的代理或源码仓库取得模块,再计算校验和;项目已有 go.sum 时先与其中记录比对,缺少记录时通常会借助 GOSUMDB 指定的校验和数据库确认公开模块,确认后再写入 go.sum 和模块缓存。

这个过程意味着代理不必天然被信任:即使代理返回了内容,只要它与项目已记录或公开校验记录不一致,Go 就会把问题暴露出来。私有模块可由 GOPRIVATE 或 GONOSUMDB 排除公开校验和数据库查询,但项目自己的 go.sum 仍能用于后续一致性检查。
go.sum 不是版本锁文件
go.mod 描述模块要求并参与最小版本选择,go.sum 则记录“某个具体模块版本对应什么内容”。因此,go.sum 里可能同时保留同一模块的多个历史版本,也可能有当前构建暂时不用的校验记录;看到这些行不能反推出当前一定选中了这些版本。
| 要确认的问题 | 看哪里 | 可用命令 |
|---|---|---|
| 当前构建选中了哪个版本 | 模块构建列表 | go list -m all |
| 为什么需要某个模块 | 依赖路径 | go mod why -m 模块路径 |
| 校验记录是否该增删 | go.mod、源码导入与测试共同决定 |
go mod tidy |
| 本地模块缓存是否被改过 | 模块缓存 | go mod verify |
不要把删除 go.sum 当成“刷新锁文件”。真正要升级依赖,应修改选中版本;真正要整理校验记录,应运行 go mod tidy,让 Go 根据当前模块图增删需要的校验项。
团队中怎样维护 go.sum
go.mod 与 go.sum 应一起提交到版本控制。依赖升级后先执行 go mod tidy,检查两份文件的差异,再运行测试;如果 PR 只出现大批无法解释的 go.sum 变化,应先确认是不是 Go 版本、构建标签、测试依赖或依赖升级改变了模块图。
校验本地缓存可直接运行:
go mod verify预期输出:
all modules verified如果输出具体模块被修改,就进入缓存或下载链路排查;如果只是 go.sum 增删,先用 go mod tidy 让记录回到与当前源码和模块图一致的状态。