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

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 | printf 'module example.com/t9\n\ngo 1.21\n\nrequire github.com/pkg/errors v0.8.1\n' > go.mod |
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。
graph LR A["app<br/>主程序"] --> B["lib1<br/>要 v0.8.1"] A --> C["lib2<br/>要 v0.9.1"] B --> D["pkg/errors<br/>v0.8.1"] C --> E["pkg/errors<br/>v0.9.1"] D -.->|被丢弃| F["实际编译用<br/>v0.9.1"] E ==>|胜出| F
go mod graph 能把这两条边原样打出来,它是排查版本为什么升上去的第一手材料。
1 | go mod graph |
1 | example.com/app example.com/lib1@v0.0.0 |
看到 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 | sed -i 's/h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=/h1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=/' go.sum |
1 | verifying github.com/pkg/errors@v0.9.1: checksum mismatch |
注意它连自己算出来的哈希都打出来了,你手里有两个值可以直接比,不用去猜。这一段输出我第一次看到的时候正在一家公司的内网里,第一反应是完了是不是中毒了,冷静下来才发现是自己手贱改了文件。
go.sum 缺行的报错长得不一样,短得多。
1 | main.go:6:2: missing go.sum entry for module providing package github.com/pkg/errors |
缺一行就算不出来,这件事说明 go.sum 是白名单制的,里面没记的模块,构建不会替你猜,哪怕缓存里就有那个 zip。go mod verify 是主动查账的命令,它把本地缓存里的每个模块重新算一遍哈希,和 go.sum 比。
1 | go mod verify |
1 | all modules verified |
这句话在你怀疑缓存被污染的时候是第一句该敲的。
要是它报了 mismatched checksum,先别急着删缓存,先把 go.sum 的改动记录翻出来看一遍。
replace 和 exclude
两个指令管的是相反的事。
一个是换来源,一个是划禁区。
replace 改的是取件地址,不是依赖图。
1 | go mod edit -replace github.com/pkg/errors=github.com/pkg/errors@v0.8.1 |
1 | require github.com/pkg/errors v0.9.1 // indirect |
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 | go mod edit -exclude github.com/pkg/errors@v0.9.1 |
1 | go: dropping requirement on excluded version github.com/pkg/errors v0.9.1 |
排除掉一个版本之后,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 | sed -i 's/^go 1.26.0$/go 1.21/' go.mod |
1 | go: updates to go.mod needed; to update it: |
想知道 tidy 到底会改什么,又不想让它真改,用 -diff。
1 | go mod tidy -diff |
1 | diff current/go.mod tidy/go.mod |
这个参数我在 CI 里见过,用法是跑一遍,有 diff 就失败,等于强制所有人提交前 tidy 过。
这一招比写检查清单管用。
再往上一层是 toolchain。如果你写的 go 行比当前装的 Go 还新,默认行为不是报错,是去下载一个新工具链,它会真的去下一个。
1 | go: downloading go1.30.0 (windows/amd64) |
我这台机器上因为网络和版本都不存在,下不到才失败。想禁掉这个行为,设 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 | # github.com/pkg/errors v0.9.1 |
## 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,让它自己重新算。









