【笔记】Go 工具链的包、模块与版本边界

理解 Go 命令时，最容易混淆的是四个不同层次：命令行选中了哪些源码，源码组成什么 package，package 属于哪个 module，以及由哪一版 toolchain 执行命令。

一句话心智模型是：go 命令先确定构建单元和模块图，再选择满足版本约束的工具链；package 可见性、module 版本选择和 compiler 语言模式分别在不同边界生效。

1. 从命令行到编译器的完整链路

flowchart TD
    A[go build / go test / go mod tidy] --> B[解析 package pattern 或 .go 文件列表]
    B --> C[加载 package import graph]
    C --> D[根据 go.mod 加载 module graph]
    D --> E[MVS 选择每个 module 的唯一版本]
    E --> F[检查 internal 等 package 可见性]
    F --> G[按 go directive 对应的语言版本编译]

这几张图互相关联，但不能混为一谈：

• package graph 的边是源码中的 import；
• module graph 的边来自各版本 go.mod 的 require；
• MVS 在 module graph 上选版本，不负责判断 package 是否真的被某段源码导入；
• internal 限制根据 import path 和目录祖先判断，与 module 的 public/private 仓库属性无关；
• toolchain 是实际运行的 go 命令及 compiler，go directive 则定义模块要求的最低 Go 版本和语言语义基线。

2. go build 构建的是 package，不是“一个目录”

常见调用有两种语义。

2.1 package 参数

go build ./cmd/server
go build ./...

./cmd/server 是相对当前 module 解析的 package pattern。目录只是定位 package 的方式，不存在一套独立的“目录构建模式”。

构建单个 main package 时，go build 默认写出可执行文件；构建单个非 main package 或多个 package 时，默认只验证它们能够完成编译，随后丢弃构建产物。-o 可以覆盖默认输出规则。

2.2 显式 .go 文件列表

go build main.go helper.go

这不是让 Go 自动寻找同目录其余源码，而是用列出的文件合成一个临时 package：

• 文件必须来自同一个目录；
• 未列出的同目录 .go 文件不会参与构建；
• 若它是 main package，默认输出名取第一个源文件的文件名；
• 它绕开了正常 package 文件选择，因此通常只适合小实验，不适合作为项目构建入口。

所以“是否产出二进制”最终看构建结果是否包含可执行的 main package，而不是参数看起来像目录还是文件。

3. package graph 与 module graph

假设源码导入 example.com/a/pkg，Go 需要先确定这个 package 由哪个 module version 提供。为此，命令会从主模块的 go.mod 出发加载 module graph，并用 Minimal Version Selection（MVS）为每个 module path 选择版本。

MVS 的“minimal”不是寻找互联网上满足约束的最低版本，而是：在构建列表已经提出的版本中，为同一个 module path 选最高版本。它的重点是可预测地合并版本要求，不是 SAT 求解式的全局降级搜索。

3.1 为什么错误信息里会出现两个看似无关的 module

go mod tidy 不只处理主程序当前直接 import 的 package。它需要补齐或删除 go.mod、go.sum 中的依赖，使模块能够满足指定 Go 版本下的 package 加载要求。因此，它可能在加载某条测试 import chain 时，同时发现构建列表中的另一个 module version 无法读取。

典型错误可以拆成两层：

package A tested by
package A.test imports
package B:
module C@version: invalid version: unknown revision

• 前半段是“当前正在为何种 package 加载需求工作”的上下文；
• 最后一段才是失败的直接原因：构建列表要求的 C@version 不存在或不可访问。

不能仅凭文本相邻，就推断 B 在源码上 import 了 C。正确排查顺序是：

1. 找出无效版本来自主模块的 require、依赖模块的 go.mod，还是 replace；
2. 用 go mod graph、go mod why -m <module> 和 go list -m -json all 检查图关系；
3. 单独验证该 revision 是否存在、私有仓库鉴权是否成功；
4. 再判断 package import chain 是否只是错误发生时的加载上下文。

3.2 module graph pruning 会改变“需要加载多少图”

现代 Go module 支持 graph pruning 和 lazy module loading。主模块的 go 版本会影响加载规则；不同 Go 版本读取同一组历史 go.mod 时，可能需要遍历的传递依赖范围不同。

因此，不宜把模块解析理解成固定的“先下载当前 module，再深度优先递归所有子 module”。它更接近按当前 package 需求和 go.mod 元数据逐步扩展图，并在必要时补充加载。

4. go 与 toolchain directive 解决不同问题

module example.com/demo

go 1.23
toolchain go1.25.4

4.1 go 1.23

go directive 是模块的最低 Go 版本要求，也是模块内语言语义和部分 go 命令行为的版本基线。自 Go 1.21 起，它是必须满足的最低版本约束，而不只是提示。

较新的 compiler 能够编译较旧语言版本的代码。go 命令会把选定的语言版本传入编译流程；可以通过下面的命令观察实际 compiler invocation：

go build -x ./...
go build -work -x ./...

输出中的 compile 命令可看到类似 -lang=go1.23 的参数。-work 会保留临时工作目录，便于继续检查生成物。

4.2 toolchain go1.25.4

toolchain directive 给出建议使用的 Go toolchain。它主要服务开发主模块时的工具链选择，不会把所有依赖库的使用者强制锁死在这个精确补丁版本。

在默认的 GOTOOLCHAIN=auto 下，当前 go 命令会同时查看：

• 当前安装或启动的 toolchain；
• go directive 要求的最低版本；
• toolchain directive 建议的版本。

若本地 toolchain 太旧，Go 可以查找或下载更合适的 toolchain 后重新执行。最终选择不能低于 go directive 的要求。因此，toolchain 写成低于 go 的版本没有实际降级意义；写成较高版本则表示开发该模块时偏好较新的工具链。

这里也没有“只能高一个 major”的规则。Go toolchain 名称长期处于 go1.x 版本序列，比较的是 Go release ordering，而不是借用语义化版本的 major 跨度规则。

可用以下命令观察选择结果：

go version
go env GOTOOLCHAIN
GOTOOLCHAIN=local go version
GOTOOLCHAIN=auto go version

5. internal 是基于目录祖先的导入边界

官方规则是：位于名为 internal 的目录之内或之下的代码，只能被以该 internal 的父目录为根的目录树中的代码导入。

例如：

root/a/
├── b/                         # import 方
└── internal/
    └── b/
        └── internal/
            └── c/             # 目标 package

目标 c 的 import path 中有两个 internal。每一个都形成约束：

1. 外层 root/a/internal 要求 import 方位于 root/a 子树，root/a/b 满足；
2. 内层 root/a/internal/b/internal 要求 import 方位于 root/a/internal/b 子树，root/a/b 不满足。

因此导入失败。实践中可以从目标路径最右侧的 internal 开始检查；只要任意一层不满足，就没有必要继续。

6. 排障时不要跨层猜因果

遇到 Go 工具链问题时，按下面顺序定位：

1. 命令行选择层：传的是 package pattern 还是 .go 文件列表？
2. package 层：真实 import chain 是什么？build tags 和测试 package 是否参与？
3. module 层：哪个 module version 提供 package？版本要求从哪里进入图？
4. 可见性层：是否触发 internal 等目录规则？
5. toolchain 层：实际运行哪个 Go 版本？模块的语言版本是什么？

把错误最后一行当作直接失败，把前面的 package chain 当作加载上下文，通常比从整段错误文本猜一条源码依赖链更可靠。

7. 复习索引

• go build ./pkg：按 package 加载目录内符合条件的源码。
• go build a.go b.go：只用显式文件合成 package。
• package graph 来自 import；module graph 来自各版本 go.mod。
• MVS 对同一 module path 选择图中提出的最高版本。
• go directive：最低版本、语言语义和命令行为基线。
• toolchain directive：开发主模块时建议使用的工具链。
• internal：每一层都按其父目录树检查 import 方。
• 排错：package chain 是上下文，最后的 module/version 错误才是直接原因。

8. 核验入口

• Go command documentation
• Go Modules Reference
• Go Toolchains
• Go 1.26 cmd/go package loader