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;首次执行需要能访问模块源或代理。

bash
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 ... 提示):

text
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 模块下载、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 版本、构建标签、测试依赖或依赖升级改变了模块图。

校验本地缓存可直接运行:

bash
go mod verify

预期输出:

text
all modules verified

如果输出具体模块被修改,就进入缓存或下载链路排查;如果只是 go.sum 增删,先用 go mod tidy 让记录回到与当前源码和模块图一致的状态。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

看懂 go.sum 为什么存在

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通