go.mod 记你要什么,go.sum 记你拿到了什么

难度 ★★☆☆☆ · 前置:装完 Go 的第一天,我卡在 GOPATH 上 | 一句话结论:go.mod 里写的版本号写的不是我要哪个版本,而是我至少要哪个版本,最终选哪个由整张依赖图决定;go.sum 记的是每个模块内容的哈希,对不上就中止构建,不是警告。

我最早做的一件蠢事是把别人项目的 go.mod 整个复制过来,想着版本都定死了,我这边的构建总能和他一样。结果同一份代码在我机器上编出来的行为不一样,他那边一个库返回的错误信息是新的格式,我这边还是老的,我对着屏幕比了两遍 import 路径,一个字都没差。那时候我以为 go.mod 是锁文件,像 package-lock.json 或者 Pipfile.lock 那样,写什么就是什么,写 v0.8.1 就该编进 v0.8.1。这个念头一旦成立,后面所有异常都会被解释成别的原因,我甚至去查了机器的编码问题。

这个理解错了,而且错得不算浅,它让我在接下来的两天里一直在找错的方向。真正的原因是那几行 require 表达的是一个下限,不是一个具体版本,Go 拿这个下限去算整张依赖图,算出来的结果可能比你写的高。你写 v0.8.1,别的地方有谁写了 v0.9.1,最后大家统一用 v0.9.1,你那一行看起来没变,实际起作用的是高的那个。这套规则有个名字,最小版本选择,英文缩写 MVS,官方文档在 go help modules 里有一节讲,不长,值得读完,读完再回头看那些升级后突然改了行为的 bug,很多都能对上号。

require 写的是下限

先把这个说法验一下,不然后面全是空谈。

1
2
3
printf 'module example.com/t9\n\ngo 1.21\n\nrequire github.com/pkg/errors v0.8.1\n' > go.mod
go mod tidy
go list -m github.com/pkg/errors
1
github.com/pkg/errors v0.8.1

这个库现在的最新版是 v0.9.1,go mod tidy 明明去镜像上查过版本列表,最后还是老老实实停在 v0.8.1。这说明 MVS 不会因为新版存在就升,它只在你要求的下限里挑最高的那个,你只要 v0.8.1,它就给你 v0.8.1,多的一个字节都不给。

现在把这个库同时被两个项目依赖的情况摆出来,才看得出那条规则的真正形状。我建了 lib1 和 lib2,前者要 v0.8.1,后者要 v0.9.1,主程序同时引这两个,然后 tidy 一次,go.mod 里就多出来这么一行。

1
require github.com/pkg/errors v0.9.1 // indirect

两个下限里取高的,v0.9.1,并且在后面标了 // indirect,意思是这个依赖不是我直接 import 的,是我引的库引的。lib1 想要的 v0.8.1 就这样被无声地丢掉了,它自己的 go.mod 里还写着 v0.8.1,一字未改,但它编的时候实际链进去的是 v0.9.1。

go mod graph 能把这两条边原样打出来,它是排查版本为什么升上去的第一手材料。

1
go mod graph
1
2
3
4
5
example.com/app example.com/lib1@v0.0.0
example.com/app example.com/lib2@v0.0.0
example.com/app github.com/pkg/errors@v0.9.1
example.com/lib1@v0.0.0 github.com/pkg/errors@v0.8.1
example.com/lib2@v0.0.0 github.com/pkg/errors@v0.9.1

看到 v0.8.1 那条边还活着,但 go list -m all 里只有 v0.9.1,两句话就对上号了,边在图上,版本被压过去了。

这条命令的输出很长,但它只做一件事,每一行是一条谁依赖谁的边,看的时候只盯着你要查的那个模块名往下找就行。

五个字的模块名,两秒钟就能扫完一整屏。

为什么是最小版本选择

这个设计当年让我觉得反直觉,因为所有人的直觉都是装最新的。

反直觉的地方,往往正是它值钱的地方。

Go 的选择正好相反,它认为版本越高越容易引入意外的行为变化,所以只要没有别处要求更高,就停在能满足要求的那个最低版本上。好处是构建极其稳定,一个没人动过的项目,三年后 clone 下来编出来的依赖版本和当初一模一样,不需要锁文件,go.mod 本身就是锁。这个设计在团队里最直接的效果是,别人 clone 你的代码以后编出来和你一样,不用反复核对两边的版本,而这恰恰是所有别的语言包管理器花最大力气去解决的问题,它们靠额外的锁文件去模拟,Go 干脆把它做成了算法的默认结果。坏处是升级要你自己动手,go get -u 是升到最新,go get pkg@version 是升到指定版本,两个命令都会改 go.mod 和 go.sum,改完你得重新跑测试。

这里没有 npm update 那种顺手把整棵树升一遍的默认行为,一个模块的升级不会连累别的模块跟着动,这是 MVS 给你的第二重好处,也是它敢取消锁文件的底气。

go.sum 记的是哈希,不是版本

go.sum 经常被当成 go.mod 的备份,这是第二个误解。它里面一行长这样。

1
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=

左边是模块名和版本,中间那个 h1: 开头的是这个模块所有文件按固定规则算出来的哈希,右边还有一行带 /go.mod 后缀的是 go.mod 文件本身的哈希。所以同一个版本在 go.sum 里通常占两行,一行管代码,一行管它自己的依赖声明。两行的算法不同,这也解释了为什么删 go.sum 之后重跑 tidy 出来的是同样的内容,因为哈希只由文件字节决定,不掺任何本地状态。

这个哈希存在的意义,是防中间人。你从镜像站下到的 zip,和作者传到 GitHub 上的应该完全一致,哈希就是那个一致的证明。把 go.sum 里那一串改掉一个字符,构建会直接停下,不是警告,不是重下,是中止。

1
2
sed -i 's/h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=/h1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=/' go.sum
go build ./...
1
2
3
4
5
6
7
8
9
10
verifying github.com/pkg/errors@v0.9.1: checksum mismatch
downloaded: h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
go.sum: h1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.
The bits may have been replaced on the origin server, or an attacker may
have intercepted the download attempt.

For more information, see 'go help module-auth'.

注意它连自己算出来的哈希都打出来了,你手里有两个值可以直接比,不用去猜。这一段输出我第一次看到的时候正在一家公司的内网里,第一反应是完了是不是中毒了,冷静下来才发现是自己手贱改了文件。

go.sum 缺行的报错长得不一样,短得多。

1
2
3
main.go:6:2: missing go.sum entry for module providing package github.com/pkg/errors
(imported by example.com/t2); to add:
go get example.com/t2

缺一行就算不出来,这件事说明 go.sum 是白名单制的,里面没记的模块,构建不会替你猜,哪怕缓存里就有那个 zip。go mod verify 是主动查账的命令,它把本地缓存里的每个模块重新算一遍哈希,和 go.sum 比。

1
go mod verify
1
all modules verified

这句话在你怀疑缓存被污染的时候是第一句该敲的。

要是它报了 mismatched checksum,先别急着删缓存,先把 go.sum 的改动记录翻出来看一遍。

replace 和 exclude

两个指令管的是相反的事。

一个是换来源,一个是划禁区。

replace 改的是取件地址,不是依赖图。

1
2
go mod edit -replace github.com/pkg/errors=github.com/pkg/errors@v0.8.1
go mod tidy
1
2
require github.com/pkg/errors v0.9.1 // indirect
replace github.com/pkg/errors => github.com/pkg/errors v0.8.1

require 那行还是写着 v0.9.1,但实际拉下来的是 v0.8.1,go.sum 里也只有 v0.8.1 的两行。这个组合读起来矛盾,实际是两层,require 记的是依赖图算出来的结果,replace 记的是算完之后再去哪取,后者覆盖前者。这两层分开记的好处是,你把临时改动删掉,require 那一行立刻恢复成原本算出来的样子,不需要重新推一遍依赖图。

replace 最常见的用途不是降版本,是把一个远端模块指向本地目录,改别人的库改到一半还没提交,就用这个挂上去跑。replace example.com/lib1 => ../lib1 这种写法在 go.mod 里很常见,它是带路径的,只在本地生效,go mod tidy 之后不会自动消失,这一点和 go.sum 不一样,工具不会主动帮你清理这种看起来像笔误的行。

有一条坑要记住,replace 不参与传递。你的 go.mod 里写了的 replace,对别人引你的代码时不起作用,所以拿它做临时降级,别指望合到主干还在。

exclude 是把这个版本关在门外。

门外的事,它管不了。

1
2
go mod edit -exclude github.com/pkg/errors@v0.9.1
go mod tidy
1
2
3
4
go: dropping requirement on excluded version github.com/pkg/errors v0.9.1
go: finding module for package github.com/pkg/errors
go: downloading github.com/pkg/errors v0.9.0
go: found github.com/pkg/errors in github.com/pkg/errors v0.9.0

排除掉一个版本之后,Go 会去退一个,选出来的是 v0.9.0。这个指令的真实用处只有一个,某个版本有致命 bug 但你又不能马上改代码,先把它关在门外,等上游修好再撤掉。用完记得删,留在仓库里的 exclude 是一个定时炸弹,下次有人要升版本时会撞上一堵看不见的墙,而且报错只告诉你版本选不出来,不会告诉你是因为有这么一行排除记录在挡路,排查时得把 go.mod 从头读一遍才可能想起来。

go 那一行不是注释

go.mod 顶上那行 go 1.21 经常被当成说明书,其实它是个硬约束,决定编译器用什么语言版本给你做语法检查,也决定依赖图的解析规则。

它会被悄悄改高,这一点很多人不知道。我引了 golang.org/x/text v0.44.0,tidy 完之后原本写的 go 1.21 变成了 go 1.26.0,因为那个库自己的 go.mod 里就写着 go 1.26.0,一个模块的 go 行不能低于它依赖的任何模块。这条规则是传递的,你引的库引的库也一样,所以项目要 1.21 就够了这个判断,在加依赖的时候随时会被推翻,半夜升级一个库结果被迫把整个项目的语言版本抬上去,是很常见的一件事,尤其当你引的那几个库维护得很勤的时候。

1
2
sed -i 's/^go 1.26.0$/go 1.21/' go.mod
go build ./...
1
2
go: updates to go.mod needed; to update it:
go mod tidy

想知道 tidy 到底会改什么,又不想让它真改,用 -diff。

1
go mod tidy -diff
1
2
3
4
5
6
7
8
diff current/go.mod tidy/go.mod
--- current/go.mod
+++ tidy/go.mod
@@ -1,6 +1,6 @@
module example.com/t4

-go 1.21
+go 1.26.0

这个参数我在 CI 里见过,用法是跑一遍,有 diff 就失败,等于强制所有人提交前 tidy 过。

这一招比写检查清单管用。

再往上一层是 toolchain。如果你写的 go 行比当前装的 Go 还新,默认行为不是报错,是去下载一个新工具链,它会真的去下一个。

1
2
go: downloading go1.30.0 (windows/amd64)
go: download go1.30.0 for windows/amd64: toolchain not available

我这台机器上因为网络和版本都不存在,下不到才失败。想禁掉这个行为,设 GOTOOLCHAIN=local,报错就变成一句话。

一个环境变量,把不确定性关掉。

1
go: go.mod requires go >= 1.30.0 (running go 1.27.2; GOTOOLCHAIN=local)

这条信息里三个数字都齐了,要求多少、实际多少、为什么没自动升,比下载失败那种模模糊糊的输出好读得多。CI 环境里我一般直接设成 local,省得构建机上偷偷装进来一个谁也没审过的编译器。

vendor 是另一个答案

模块模式最不受欢迎的一点是构建要联网,第一次 clone 下来编不过,因为依赖没下。针对这个,Go 留了一条老路,go mod vendor。

跑完之后多出一个 vendor/ 目录,第三方源码整份复制进去,还附一个 modules.txt。

1
2
3
# github.com/pkg/errors v0.9.1
## explicit
github.com/pkg/errors

## explicit 的意思是这个模块在 go.mod 里被直接 require 了,没有这一行的说明是间接带进来的,文件里只有三类标记,读起来很快。有了 vendor,构建默认就不联网了,go build 直接读目录里的源码,go.sum 那套校验在这个模式下不参与,因为代码就在你仓库里。

vendor 该不该进仓库,这个问题没有统一答案。进仓库的好处是构建完全不依赖网络和镜像,CI 快,审计能直接看源码,坏处是仓库体积上去,升级依赖时的 diff 里塞满了别人的代码,代码评审没法看。我自己的习惯是库不进、服务进,判断依据简单,库是要被别人 go get 的,vendor 进去只会让别人的依赖树变重,服务是自己部署的,构建可复现比仓库干净重要。

一张表收尾

三个文件或指令的关系,整理成一张表就够了。

你在改什么 记在哪 谁来维护
我想要哪个库、至少什么版本 go.mod 的 require 手改或 go get
算出来实际生效的是哪个版本 go.mod(含 // indirect) go mod tidy
我实际拿到的那份内容对不对 go.sum 自动,不要手改
我想换个来源、或指向本地 go.mod 的 replace 手改,通常临时
我要把源码拷进仓库 vendor/ go mod vendor

五行里只有 go.sum 那一行写了不要手改,因为它是唯一一个由工具单方面维护、并且故意不给你改的余地的文件,改它一定出错。剩下四个都是给你改的,require 和 replace 手改,// indirect 和 vendor/ 交给工具。分工清楚以后,遇到依赖问题先看是哪一行出的事,判断方向就不会跑偏,这比背一堆命令有用得多。

我第一次把 go.sum 冲突当成 merge 冲突处理,手工挑了一边留下,结果构建直接报 SECURITY ERROR。正确的做法是删掉那几行再跑 tidy,让它自己重新算。