《Go 语言编程实战》2.1 最小版本选择与冲突排查

2.1 最小版本选择与冲突排查

卷一讲过 MVS 的规则：为每个模块选依赖图中出现过的最高「最低要求」。规则本身一句话能说完，但在 TaskHub 这种四个模块、几十个依赖的真实项目里，「谁把版本抬高了」「我明明写了 v0.14.0 为什么编到 v0.19.0」才是日常要面对的问题。

本节不复述规则，而是用两个真实模块跑一遍完整的冲突排查链路。

本节在一个独立模块里制造一次真实的版本冲突，实测 MVS 的裁决输出、go get 强制降级的报错、go mod graph 定位引入者，以及 exclude 的干预效果。

2.1.1 冲突长什么样

先建立一个最小复现场景。新建模块 mvsdemo，它直接依赖 golang.org/x/text v0.14.0：

$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get golang.org/x/text@v0.14.0
go: added golang.org/x/text v0.14.0

此时 go.mod 里 require golang.org/x/text v0.14.0。现在引入另一个模块 golang.org/x/net v0.30.0——它内部要求 x/text v0.19.0：

$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get golang.org/x/net@v0.30.0
go: added golang.org/x/net v0.30.0
go: upgraded golang.org/x/text v0.14.0 => v0.19.0

注意那行 upgraded：你显式写的 v0.14.0 被 MVS 抬到了 v0.19.0。这就是冲突的第一种表现——不是报错，而是静默升级。

$ GOTOOLCHAIN=go1.27.0 go list -m golang.org/x/text golang.org/x/net
golang.org/x/text v0.19.0
golang.org/x/net v0.30.0

2.1.2 为什么会静默升级

go.mod 里的版本是最低要求（minimum version），不是「锁定」。MVS 的工作方式是：收集依赖图里所有对 x/text 的版本要求——你要求 v0.14.0，x/net v0.30.0 要求 v0.19.0——然后取最大值 v0.19.0。

这个行为初看反直觉，其实是为了可复现：只要依赖图不变，解析结果永远唯一，不会因为安装顺序不同而得到不同版本（npm 就吃过这个亏）。代价是你不能「只降级一个模块」而不动它的上游。

2.1.3 强制降级会怎样

假设你出于某种原因必须用 x/text v0.14.0，同时保留 x/net v0.30.0。把两个版本要求写在同一条命令里：

$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct \
    go get golang.org/x/net@v0.30.0 golang.org/x/text@v0.14.0
go: golang.org/x/net@v0.30.0 requires golang.org/x/text@v0.19.0,
    not golang.org/x/text@v0.14.0

这是冲突的第二种表现——显式报错。go get 直接告诉你矛盾在哪：x/net v0.30.0 明确要求 x/text ≥ v0.19.0，你要求 v0.14.0，两者不可能同时满足。

实测这时 go get 不会改任何东西，go list 仍是上一步的版本：

$ GOTOOLCHAIN=go1.27.0 go list -m golang.org/x/net golang.org/x/text
golang.org/x/net v0.30.0
golang.org/x/text v0.19.0

（报错后 go get 不写入任何改动，版本仍停在 2.1.1 结束时的 x/net v0.30.0 / x/text v0.19.0。）

2.1.4 单条 go get 会「顺手」改别的

冲突排查里最容易踩的坑是：go get A@vX 会重算整个依赖图。实测从「已升级到 v0.19.0」的状态执行：

$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get golang.org/x/text@v0.14.0
go: downloading golang.org/x/net v0.24.0
go: downgraded golang.org/x/net v0.30.0 => v0.24.0
go: downgraded golang.org/x/text v0.19.0 => v0.14.0

它成功了，但代价是把 x/net 从 v0.30.0 降到了 v0.24.0——因为只有 v0.24.0 这个版本的 x/net 才允许 x/text v0.14.0。你以为只动了一个模块，实际上动了一串。

排查时的纪律：改依赖版本后，先看 go get 的完整输出，再看 git diff go.mod，确认没有意料之外的连带变更。

2.1.5 用 go mod graph 定位引入者

当你在 go.mod 里看到某个版本被抬高，第一反应是「谁要求了它」。go mod graph 每行是一条「依赖方 → 被依赖方@版本」的边：

$ GOTOOLCHAIN=go1.27.0 go mod graph | grep 'x/text@'
example.com/mvsdemo golang.org/x/text@v0.14.0
golang.org/x/net@v0.24.0 golang.org/x/text@v0.14.0
golang.org/x/text@v0.14.0 golang.org/x/tools@v0.6.0
golang.org/x/text@v0.14.0 golang.org/x/mod@v0.8.0
golang.org/x/text@v0.14.0 golang.org/x/sys@v0.5.0

读法：箭头左边是要求方，右边是被要求方。第一行说明「我的主模块要求了 x/text v0.14.0」；第二行说明「x/net v0.24.0 也要求了 x/text v0.14.0」。grep 'x/text@v0.19.0' 就能找出所有把版本抬到 v0.19.0 的模块。

go mod graph 的输出可能非常大（几百上千行）。工程里的用法是配合 grep 和 sort -u：

# 找出所有对某模块提出要求的模块，去重
$ GOTOOLCHAIN=go1.27.0 go mod graph | grep ' golang.org/x/text@' | awk '{print $1}' | sort -u
example.com/mvsdemo
golang.org/x/net@v0.24.0

2.1.6 go mod why：这个依赖到底谁在用

go mod graph 看的是「版本要求」，go mod why 看的是「代码引用链」：

$ GOTOOLCHAIN=go1.27.0 go mod why -m golang.org/x/text
# golang.org/x/text
example.com/mvsdemo
golang.org/x/text/language

输出是从主模块到该包的最短引用链：主模块 import 了 x/text/language，所以 x/text 是必需的。

如果输出是下面这样，说明这个依赖已经没人用了：

$ GOTOOLCHAIN=go1.27.0 go mod why -m golang.org/x/net
# golang.org/x/net
(main module does not need module golang.org/x/net)

(main module does not need ...) 是 go mod tidy 会删掉它的信号。排查依赖时，why 比 graph 更贴近「这个依赖还活着吗」这个问题。

2.1.7 用 exclude 干预

当你确认某个版本有 bug、必须跳过它时，用 exclude：

$ GOTOOLCHAIN=go1.27.0 go mod edit -exclude=golang.org/x/text@v0.19.0
$ GOTOOLCHAIN=go1.27.0 go mod tidy
$ GOTOOLCHAIN=go1.27.0 go list -m golang.org/x/text
golang.org/x/text v0.43.0

exclude 告诉 MVS「这个版本不要选」，MVS 会跳过它、改选一个更高的可用版本。注意 exclude 的语义是排除一个具体版本，不是「排除所有高于它的版本」——如果你排除了 v0.19.0，而图里还有 v0.20.0，那 v0.20.0 照样会被选中。

2.1.8 冲突排查的标准流程

把本节用到的命令串成一条可复用的流程：

1. go list -m <module>          → 当前解析到的版本是什么
2. go mod graph | grep <module> → 谁提出了版本要求
3. go mod why -m <module>       → 这个依赖还被代码引用吗
4. go mod tidy                  → 清理无用依赖，重新解析
5. go get <module>@<version>    → 指定版本，观察连带变更
6. git diff go.mod go.sum       → 确认变更范围符合预期

第 6 步经常被跳过，但它是最重要的一步：版本冲突的很多「诡异现象」，根源都是某次 go get 顺手改了别的模块而你没注意。

2.1.9 冲突的三种表现对照

三者的共同点是：根因都在「最低要求」而非「锁定版本」这个模型上。理解了这一点，你就不会再问「我明明写了 v0.14.0 为什么没用」——因为你写的是「至少要 v0.14.0」，而不是「就用 v0.14.0」。

2.1.10 TaskHub 里的实际约束

回到 TaskHub 的四个模块。每个模块有自己的 go.mod，工作区会把它们统一到同一个构建列表。实践中的纪律是：

• 不要在每个模块里写死同一个依赖的版本，让它由工作区的 MVS 统一。
• 升级依赖只在工作区根做一次，然后 go work sync 把结果写回各模块。
• go.sum 冲突不要手工合并，删掉重跑 go mod tidy 生成。

2.1.11 MVS 怎么排序版本

「取最高」听起来简单，但「最高」的定义有讲究。Go 按语义化版本排序，规则和直觉略有出入：

一个常见的困惑是 +incompatible：当某个库没有 go.mod（老库）却打了 v2+ 的 tag 时，Go 会标成 v2.0.0+incompatible。+incompatible 是构建元数据，不参与版本排序——两个只有该后缀不同的版本会被视为相等。TaskHub 的纪律是：尽量避开 +incompatible 的依赖，它们往往意味着这个库还没正式采用模块。

预发布版本（-rc、-beta）默认不会被自动选中：除非你在 go.mod 里显式要求某个 -rc 版本，否则 MVS 不会挑它。要升级到预发布版必须显式写版本号：

$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct \
    go get example.com/lib@v1.3.0-rc1

2.1.12 go.sum 冲突：不要手工合并

团队协作时，go.sum 的合并冲突几乎必然出现。因为 go.sum 是内容哈希的集合，两个人各自新增依赖后，合并结果可能既包含 A 的条目又包含 B 的条目，看起来「都对」，实则有一方的条目已经过期。

处理原则只有一条：go.sum 冲突一律不手工合并，删掉重生成。

$ rm go.sum
$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go mod download
$ GOTOOLCHAIN=go1.27.0 go mod tidy

go mod download 会根据 go.mod 重新拉取并写入 go.sum。之所以敢这么做，是因为 go.sum 里的哈希可以随时从 sumdb 重新获取，它不是唯一真相来源，go.mod 才是。

要验证本地缓存与 go.sum 是否一致，用：

$ GOTOOLCHAIN=go1.27.0 go mod verify
all modules verified

all modules verified 说明 GOMODCACHE 里每个模块的字节内容都和 go.sum 记录的哈希吻合。如果某次构建报 checksum mismatch，多半是缓存损坏，删掉对应目录重下即可，不必清空整个缓存。

2.1.13 一份可复现的依赖快照

MVS 保证「给定 go.mod 集合，解析结果唯一」。但前提是 go.mod 集合本身被完整记录——包括间接依赖。这就是 // indirect 条目存在的意义：它们把上游 go.mod 里的最低要求也固化下来，避免上游改了自己的 go.mod 就悄悄改变你的解析结果。

因此有一条实践纪律：任何改动依赖图的操作之后，都要跑一次 go mod tidy。它会把 // indirect 补全到当前真实需要，删掉无用的，让 go.mod 始终是一份完整的快照。

$ GOTOOLCHAIN=go1.27.0 go mod tidy
$ git diff --stat go.mod go.sum

CI 里可以加一条检查：go mod tidy && git diff --exit-code go.mod go.sum。如果 tidy 之后 go.mod 有变化，说明提交时漏跑了 tidy，直接失败。

下一节我们处理 MVS 之外的三种干预手段：升级到最新、用 replace 指向 fork、以及如何让私有模块被正确解析。

阅读导航：上一节：1.3 脚手架与代码生成 · 下一节：2.2 升级、replace 与私有模块 。