《Go 语言编程入门》7.2 go.mod/go.sum 与最小版本选择

7.2 go.mod/go.sum 与最小版本选择

上一节我们把 TaskAPI 拆成了三个包，但还没碰 go.mod 的内容——它现在只有两行，看着像个摆设。其实 go.mod 是整个模块系统的中枢：它声明模块身份、语言版本、依赖集合，甚至能改写依赖的解析结果。理解它，你才能在依赖出问题时不再靠「删掉 go.sum 重来」这种玄学手段。

本节把 TaskAPI 的 go.mod 逐行解剖，并用一个本地模块 example.com/tasklib 充当依赖，实测 go mod tidy、go list -m all、go mod graph、go mod why 四条排查命令。本节不引入任何真实第三方库，全部依赖用一个本地 replace 模拟，保证离线可复现。

7.2.1 go.mod 的六个指令

go mod init taskapi 生成的文件只有两行，但 go.mod 的完整语法远不止于此。逐条看：

module taskapi

go 1.27.0

toolchain go1.27.0

require example.com/tasklib v0.3.0

replace example.com/tasklib => ./third_party/tasklib

exclude example.com/tasklib v0.2.0

注意 require 里的版本是最低版本（minimum version），不是「锁定版本」。这是理解 Go 依赖模型的钥匙，7.2.6 会展开。

7.2.2 go 与 toolchain：两个版本不是一个东西

初学者最容易混淆这两行。它们的含义完全不同：

• go 1.27.0 是语言版本。它告诉编译器「这个模块按 Go 1.27 的语义编译」。它影响语言特性和标准库行为，比如 go 1.22 起 for range 的循环变量语义变化、go 1.24 起泛型别名可用。
• toolchain go1.27.0 是工具链建议。当本机默认工具链低于它时，Go 会尝试自动下载并使用指定工具链。它不影响语言语义，只影响「用哪个 go 二进制来编译」。

写 toolchain 的场景是团队统一：有人装了 go1.26，有人装了 go1.27，只要 go.mod 写了 toolchain go1.27.0，大家就会用同一套编译器。本卷统一用 GOTOOLCHAIN=go1.27.0 环境变量来固定版本，效果类似但更显式。

$ GOTOOLCHAIN=go1.27.0 go env GOTOOLCHAIN GOVERSION
go1.27.0
go1.27.0

两个值一致，说明当前进程确实用的是 go1.27.0 工具链。

7.2.3 go.sum 校验什么

go.sum 里每一行都是 模块路径 版本 哈希。同一个「模块+版本」通常有两行：

example.com/tasklib v0.3.0 h1:AbCd...=
example.com/tasklib v0.3.0/go.mod h1:EfGh...=

• 第一行是整个模块 zip 包的哈希。
• 第二行（带 /go.mod）是该模块 go.mod 文件的哈希。

为什么校验两个？因为 MVS 在裁剪依赖图时，可能只需要读一个模块的 go.mod 而不下载它的全部源码。只校验 go.mod 就能快速确认依赖图可信，不必先把整个模块拉下来。

go.sum 的三个要点：

1. 它是内容校验，不是版本锁。它不记录「该用哪个版本」，只记录「某版本的字节内容应当是什么」。
2. 它能防篡改，也能防「同版本不同内容」。这正是它比 package-lock.json 更严格的地方。
3. go mod tidy 会增删 go.sum 条目，go mod verify 则校验本地缓存与 go.sum 是否一致。

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

有一类情况不会产生 go.sum 条目：replace 指向本地目录时。本地目录的内容随文件系统变化，哈希没有意义。实测中我们的 tasklib 就属于这种——见下一节。

7.2.4 sumdb：哈希从哪里来

go.sum 的哈希不是凭空冒出来的，它由**校验和数据库（checksum database，sumdb）**背书。默认 GOSUMDB=sum.golang.org，go 命令首次拉取某模块时，会向 sumdb 查询该模块的哈希，写入本地 go.sum，之后每次都比对。

这条链保证的是：即使代理服务器被劫持，也无法悄悄替换某个版本的源码——因为哈希对不上。与 sumdb 相关的环境变量：

国内环境常把 GOPROXY 设为 https://goproxy.cn,direct：

$ GOTOOLCHAIN=go1.27.0 go env GOPROXY GOMODCACHE
https://goproxy.cn,direct
/Users/bingrong.yan/go/pkg/mod

GOMODCACHE 是模块缓存目录。所有下载过的模块按「路径@版本」摊平存放在这里，go.sum 校验的就是这些文件的哈希。缓存损坏时删掉对应目录再 go mod download 即可，不必清空整个缓存。

7.2.5 间接依赖与 // indirect

go.mod 里 require 块中有些条目带 // indirect 注释：

require (
	example.com/tasklib v0.3.0
	golang.org/x/text v0.14.0 // indirect
)

// indirect 表示这个依赖不是本模块源码直接导入的，而是被某个直接依赖拉进来的。它的存在意义是让 MVS 的输入确定：只有把所有间接依赖的「最低要求」也写进 go.mod，构建结果才可复现，不依赖上游 go.mod 的当前内容。

go mod tidy 会自动维护这两类条目：它会扫描全部源码的 import，算出直接依赖；再顺着依赖图补全间接依赖；最后删掉不再需要的。手动维护 // indirect 几乎一定会错，交给 tidy。

7.2.6 最小版本选择（MVS）

假设 taskapi 依赖 A，A 又依赖 B v1.2.0，而 taskapi 自己直接依赖 B v1.4.0。B 到底用哪个版本？

MVS 的规则简单到反直觉：在依赖图里出现的所有版本中，为每个模块选「最高的那个最低要求」。也就是取 max(1.2.0, 1.4.0) = 1.4.0。

MVS 的关键性质是**「只增不减、可复现」：给定同一份 go.mod 集合，解析结果永远唯一，不会像 npm 那样因为安装顺序不同而得到不同结果。代价是你无法「降级」一个被间接依赖拉高的版本**——这时就要用 exclude 或 replace 干预。

用 go list -m all 看当前解析结果，用 go mod graph 看依赖图：

$ GOTOOLCHAIN=go1.27.0 go list -m all
taskapi
example.com/tasklib v0.0.0-00010101000000-000000000000 => /tmp/gowork/tasklib

$ GOTOOLCHAIN=go1.27.0 go mod graph
taskapi example.com/tasklib@v0.0.0-00010101000000-000000000000
taskapi go@1.27.0
example.com/tasklib@v0.0.0-00010101000000-000000000000 go@1.27.0
go@1.27.0 toolchain@go1.27.0

go list -m all 的 => 表示这一项被 replace 改写了目标路径。go mod graph 每行是「依赖方 → 被依赖方」的边，用它可以快速定位「是谁把某个版本拉进来的」。

7.2.7 用 replace 做本地联调

真实项目里，replace 最常见的用途是本地联调：你想同时改 tasklib 和 taskapi，不想每改一行就 go get 一次。做法是把依赖指向本地目录：

$ GOTOOLCHAIN=go1.27.0 go mod edit \
    -replace=example.com/tasklib=/tmp/gowork/tasklib

$ GOTOOLCHAIN=go1.27.0 go mod tidy
go: found example.com/tasklib in example.com/tasklib v0.0.0-00010101000000-000000000000

tidy 之后，go.mod 里 require 的版本变成了 v0.0.0-00010101000000-000000000000——这是一个伪版本（pseudo-version），00010101 是时间戳占位，表示「本地替换，无真实版本」。同时本地 replace 不写 go.sum，因为目录内容无法用哈希固定。

go mod why 用来回答「为什么这个依赖在我的模块里」：

$ GOTOOLCHAIN=go1.27.0 go mod why -m example.com/tasklib
# example.com/tasklib
taskapi/cmd/taskapi
example.com/tasklib

输出是从 main 包到该模块的引用链。如果某条链只到「(main module does not need module …)」，说明这个依赖其实已经没人用了，可以 go mod tidy 清掉。

7.2.8 语义化版本与伪版本

Go 的版本号遵循语义化版本（semver）：vMAJOR.MINOR.PATCH，例如 v1.4.0。v0.x.y 表示「尚不稳定，API 可能随时变」。除此之外还有一类伪版本，形如：

v0.0.0-20260108120000-abcdef123456
v0.0.0-00010101000000-000000000000

伪版本由「基础版本 + 时间戳 + 提交哈希」拼成，出现在两种场合：

理解伪版本能让你在 go.sum 里不再被一长串数字吓到：它只是「没有正式 tag 时，用时间戳和哈希唯一标识一次提交」。

7.2.9 依赖排查速查

把本节会用到的高频命令与典型报错放一起：

7.2.10 改 go.mod 的正确姿势

最后给一张「想做什么 → 用什么命令」的对照表，避免手改 go.mod 改坏格式：

go.mod 是「人也能读、但应由工具写」的文件。手改不是不行，只是容易漏掉格式规范（比如 require 块的对齐、// indirect 注释），交给 go mod edit 与 go mod tidy 更稳。

下一节我们把依赖治理讲透：go get 的版本查询语法、go mod tidy 到底删了什么、vendor/ 目录该不该提交、以及如何用 GOFLAGS=-mod=vendor 锁定构建。

阅读导航：上一节：7.1 包的声明、导入与可见性 · 下一节：7.3 go get/tidy/vendor 与依赖治理 。