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

理解 Go 命令时，最容易出现的错觉是：命令行上写了一个目录，Go 就是在“构建目录”；源码 import 了一个 package，Go 就直接按文件夹名字去找；go.mod 写了一个 Go 版本，实际运行的 compiler 就必然是这个版本。

这些说法都把不同层次压成了一件事。真正需要分开的是：

• 命令行参数如何定位 package；
• package 在程序中如何用 import path 标识；
• import path 由哪个 module version 提供；
• package 之间为什么可以或不可以相互 import；
• 当前命令最终由哪套 Go toolchain 执行。

一句话心智模型是：命令行路径负责找到 package，import path 负责标识 package，module graph 负责确定代码版本，Go toolchain 负责执行这次命令。

1. 一次 Go 命令经过哪些边界

Go 1.21 之后，一次 module-aware Go 命令大致有两个阶段。

flowchart TD
    A[Shell 通过 PATH 启动 go] --> B[读取 GOTOOLCHAIN]
    B --> C{是否允许 auto / path 切换}
    C -->|no| D[使用固定的默认 toolchain]
    C -->|yes| E[读取 go.work 或主模块 go.mod]
    E --> F{项目是否要求更新 toolchain}
    F -->|no| D
    F -->|yes| G[从 PATH 查找或下载 toolchain]
    D --> H[最终 toolchain 执行命令]
    G --> H
    H --> I[解析 package 参数或 .go 文件列表]
    I --> J[按需交替加载 package graph 和 module graph]
    J --> K[确定每个 import path 的代码来源]
    K --> L[检查 internal 等可见性规则]
    L --> M[按各 package 的语言版本编译和链接]

这张图最重要的两个修正是：

1. toolchain 选择发生在命令启动早期，不是等 module graph 构建完才选 compiler；
2. package graph 和 module graph 不是两张完全独立、严格按先后顺序生成的图。Go 会根据 package 加载需求和 go.mod 元数据逐步扩展 module graph，并利用 graph pruning 减少不必要的加载。

只看版本号仍然容易把工具链部分重新压成一层。更稳定的理解方式是继续拆成五个问题：

声明层：go.mod / go.work 要求或建议什么？
供应层：PATH、版本管理器或下载机制能提供哪些 toolchain？
选择层：GOTOOLCHAIN 与项目声明最终选中哪一个？
消费层：哪一次 go 命令实际使用选中的完整 toolchain？
事实层：go version、GOROOT 和 trace 证明本次发生了什么？

配置只提供声明或选择依据，不天然等于运行事实。后面遇到 go 1.25.0、toolchain go1.25.4 和 go version go1.26.4 同时出现时，需要把它们放回不同层，而不是判断哪个版本号“覆盖”了另一个。

2. package、import path 和目录不是同一个概念

import path 听起来像一个普通路径，实际上它是连接 package、module、磁盘目录和可见性规则的核心概念。

2.1 package 是 Go 命令处理的基本代码单元

通常情况下，一个目录中通过 build constraints、文件名后缀和当前 GOOS / GOARCH 筛选后的若干 .go 文件，共同组成一个 package。这些文件使用同一个 package clause：

package http

package 才是 type checking、编译和 import 依赖的逻辑单元。目录是存放和定位它的常规方式，不是与 package 并列的另一种构建单元。

package name 是源码中的本地标识符。导入者默认用它限定对包成员的访问：

import "net/http"

func main() {
    http.ListenAndServe(":8080", nil)
}

这里 http 是 package name，net/http 才是 import path。两者通常最后一段相同，但这只是约定，不是必须相等的规则。

2.2 import path 是 package 在程序中的身份

import path 就是源码 import 声明中的字符串：

import "fmt"
import "net/http"
import "example.com/acme/service/internal/store"

它回答的不是“package name 叫什么”，而是“这次构建中究竟是哪一个 package”。一个程序中的每个 package 都必须有唯一的 import path，因此不同 module 完全可以同时存在 package name 都叫 config 的 package：

example.com/a/config
example.com/b/config

它们的 package name 可以都是 config，但 import path 不同，所以是两个不同的 package。

在 module 模式下，主模块内 package 的 import path 通常由两部分组成：

package import path = module path + package 相对 module 根的子目录

例如：

// go.mod
module example.com/acme/service

磁盘目录                              import path
<module-root>/                          example.com/acme/service
<module-root>/internal/store/           example.com/acme/service/internal/store
<module-root>/cmd/server/               example.com/acme/service/cmd/server

四个相似名字可以用同一个 package 对齐：

概念	示例	作用
package name	store	源码中访问 package 成员时使用的本地名字
package import path	example.com/acme/service/internal/store	识别究竟导入哪一个 package
module path	example.com/acme/service	识别管理这组 package 版本的 module
文件系统路径	/work/service/internal/store	说明源码在当前机器上的存放位置

一个 module 通常提供多个 package，因此 module path 只是这些 package import path 的共同前缀。只有 module 根目录本身存在 Go package 时，才会出现“该 package 的 import path 恰好等于 module path”的情况。

对依赖 package，Go 先通过 module graph 选出提供它的 module version，再到 module cache、vendor 目录或 replace 指向的本地目录中找到源码。因此 import path 是 package 的逻辑身份，它会映射到某个磁盘目录，但它不等于某台机器上的绝对文件系统路径。

源码通常也不会把选中的 module version 写进 import path：

import "example.com/lib/log"

// go.mod
require example.com/lib v1.4.0

源码 import 回答“使用哪个 package”，go.mod 和 MVS 回答“这个 package 由哪个 module version 提供”。/v2 这类语义导入版本后缀是 module path 和 import path 的一部分，但 @v1.4.0 这类具体版本查询不会出现在普通源码 import 声明中。

2.3 命令行上的 ./cmd/server 相对哪里

Go 命令通常接受 import path 列表。但官方规则还允许在命令行上使用以 .、.. 或根路径开头的文件系统路径来定位 package。

cd /work/service
go build ./cmd/server

./cmd/server 首先相对当前工作目录 /work/service 解析，定位到：

/work/service/cmd/server

如果 /work/service 正好是声明 module example.com/acme/service 的 module 根，该 package 实际的 import path 才是：

example.com/acme/service/cmd/server

因此需要区分两件事：

• ./cmd/server 是命令行上用来定位 package 的相对文件系统路径；
• example.com/acme/service/cmd/server 是源码 import 和 package graph 中使用的 import path。

./ 默认相对当前工作目录，不是默认相对 module 根。如果当前位于 /work/service/internal，那么 go build ./store 定位的是 /work/service/internal/store。-C dir 会在解析这些命令行文件或路径之前先切换工作目录。

可以直接查看命令行路径最终定位到的 import path：

go list -f '{{.ImportPath}}' ./cmd/server

源码中的 import "./util" 和命令行上的 go build ./util 不是一回事。正常 module / workspace 内的 Go 源码不能使用相对 import；命令行则可以用相对文件系统路径定位 package。

2.4 package pattern 和 ... 到底匹配什么

一个参数包含一个或多个 ... 时，它才成为这种意义上的 package pattern。... 由 Go 命令展开，不是 Shell glob。

... 的精确语义是匹配任意字符串，包括空串和包含 / 的字符串。它不是“只匹配一个完整目录层级”。尾部的 /... 可以连同前面的 / 一起匹配空串，所以 net/... 同时匹配 net 和 net/http。

参数	定位或匹配范围
.	当前工作目录中的一个 package
./cmd/server	当前工作目录下 cmd/server 中的一个 package
./...	当前工作目录及其子树中匹配到的 package
./cmd/...	当前工作目录下 cmd 子树中匹配到的 package
net/...	net 和以 net/ 开头的 package
all	主模块或 workspace modules 的 package，以及它们的依赖和相关测试依赖
std	标准库 package
cmd	Go 仓库中的 command 及其 internal library

./... 不等于“无条件从 module 根扫描整个 module”。它从当前工作目录开始匹配，并继续受 module / workspace 和 vendor 规则约束。普通 wildcard 不会穿过 vendored package path 中的 vendor 元素，除非 pattern 显式写出 vendor。

3. go build 的两种输入语义

go build 的官方定位是：编译 import path 指定的 package 及其依赖，但不安装结果。“不安装”不等于“永远不输出文件”；是否保留结果取决于构建目标和 -o。

两种输入形式的共同收敛点是 package，不是目录、单个文件，也不一定是正常 import path：

package path / package pattern
  → 定位已有 package
  → 按 build context 选择源文件
  ─┐
   ├→ package 构建
  ─┘
.go 文件列表
  → 只使用具名文件
  → 合成 command-line-arguments 临时 package

因此 go build 的构建颗粒度始终是 package。不同输入形式改变的是 package 如何被定位或合成。

3.1 package 参数模式

go build ./cmd/server
go build ./...
go build example.com/acme/service/cmd/server

在这条路径中，Go 先将参数解析成 package，再按当前 build context 选择目录内的源文件：

• 应用 build constraints；
• 考虑 GOOS / GOARCH 等文件名约定；
• 忽略 _test.go 文件；
• 加载源码 import 形成的 package graph。

所以 go build ./cmd/server 不是“把这个文件夹里的所有 .go 文件不加区分地丢给 compiler”，而是“定位这个 package，再按 Go 的 package 加载规则选择源文件”。

3.2 显式 .go 文件列表模式

go build main.go helper.go

当参数是一组真实的 .go 文件时，Go 进入命令行文件模式，用精确列出的文件合成一个 package：

• 所有具名文件必须来自同一目录；
• 它们必须能组成同一个 package；
• 同目录中没有列出的 .go 文件不会自动加入；
• 对这些具名文件不再应用普通 package 加载时的 build constraints 筛选；
• package 中的 imports 仍然会通过当前 module 环境正常解析。

例如 main.go 直接使用了同目录 helper.go 声明的函数，但命令只写 go build main.go，构建会因缺少该标识符而失败。但如果 main.go 写了 import "example.com/dep/pkg"，该依赖仍然会通过 module graph 定位。

为了让后续加载、编译和链接流程仍能把这组文件当作 package 处理，Go 会为合成 package 赋予特殊的伪 import path：

command-line-arguments

可以直接观察：

go list -f '{{.ImportPath}} {{.Module}}' main.go

command-line-arguments <nil>

command-line-arguments 不是源码中可以正常 import 的 package 身份，也不对应一个 module，而是 Go 内部表示“由命令行文件临时合成的 package”的特殊标识。这也说明，两种输入形式最终收敛到的是 package 处理模型，而不是都收敛成正常的 import path。

合成 package 自身没有正常 module 归属，不代表依赖解析也被关闭。main.go 导入的其他 package 仍然使用它们各自的 import path，并通过当前 module graph 定位。

因此这种模式绕过的是“根据目录自动选择当前 package 源文件”，不是把 package 构建模型、module 和依赖解析整体关闭。它适合小型实验，不适合代替工程的正常 package 构建入口。

3.3 是否保留产物要看“单个 main”和 -o

构建目标	默认行为
单个 main package	在当前目录写出可执行文件
单个非 main package	编译但丢弃最终 object，作为可构建性检查
多个 package	编译但丢弃最终结果，即使其中有多个 main package
使用 -o	按指定文件或目录保留 executable 或 object

两种输入模式的默认命名规则也不同：

• 单个 package 形式的 main package：使用 import path 的最后一个非主版本组件；example.com/foo/v2 输出 foo，不是 v2；
• .go 文件列表形式的 main package：使用第一个源文件的基本名；go build ed.go rx.go 输出 ed。

-o 指向已存在的目录，或参数以 / / \ 结尾时，Go 将它视为输出目录，并把生成的 executable 放入其中。-o 指向文件时，不能把多个 package 同时写进同一个文件。

4. package graph 和 module graph 分别解决什么

import path 不仅用来写 import，还是连接两张图的键。

4.1 package graph 说明源码使用关系

package graph 的节点是 package，节点身份由 import path 区分，边来自源码中的 import：

// example.com/app/cmd/server
import "example.com/lib/log"

example.com/app/cmd/server
  ──import──> example.com/lib/log

这张图回答“为了编译这个 package，还必须加载哪些 package”。build tags、平台文件和是否加载测试会改变实际参与的 package graph。

4.2 module graph 说明代码供应关系

module graph 的节点是带版本的 module，边来自各版本 go.mod 的 require：

require example.com/lib v1.4.0

Minimal Version Selection（MVS）会在 module graph 中对每个 module path 选择一个版本。MVS 的“minimal”不是去仓库搜索满足区间的最低版本，而是在构建列表已提出的版本中，对同一 module path 取最高版本。

选出 example.com/lib v1.4.0 后，Go 才能将 package import path：

example.com/lib/log

映射到该 module version 的 log 子目录。replace、vendor 模式和 workspace 会改变实际代码供应位置，但 package 仍然以 import path 作为逻辑身份。

module graph pruning 和 lazy loading 会减少需要读取的传递 go.mod 和 module 范围。因此模块解析不应被理解为“先下载主 module，再无条件深度优先遍历所有依赖”。

4.3 为什么错误里会同时出现两个看似无关的 module

go mod tidy 需要加载满足指定 Go 版本要求的 package，包括相关测试 package，同时还要保证 module graph 可解析。它可能在追踪某条测试 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 和 C@version 在错误文本中相邻，就推断 package B 在源码中 import 了 module C。

正确的核对方式是：

go mod graph
go mod why -m example.com/module
go list -m -json all

然后继续检查无效版本来自主模块的 require、依赖模块的 go.mod 还是 replace。

5. module 版本与 Go toolchain 版本不在同一个维度

go.mod 中可以同时出现依赖 module 版本、go directive 和 toolchain directive：

module example.com/acme/service

go 1.25.0
toolchain go1.25.4

require example.com/lib v1.4.0

它们回答的是不同问题：

声明	回答的问题
require example.com/lib v1.4.0	这次构建使用该依赖的哪个代码版本？
go 1.25.0	这个 module 最低需要多新的 Go，并使用哪一代语言和命令行为？
toolchain go1.25.4	直接维护主模块或 workspace 时，建议至少使用哪套 toolchain？
GOTOOLCHAIN	工具链选择从哪个默认值起步，是否允许继续切换或下载？
go version / go env GOROOT	这次命令最终由哪套 toolchain 执行，它来自哪里？

5.1 go directive 是最低要求，也是语言和兼容行为基线

Go 1.21 起，go directive 是强制的最低 Go 版本要求，不只是提示。当前 toolchain 低于它时：

• 允许自动切换时，Go 可以查找或下载更高 toolchain；
• 固定使用旧 toolchain 时，加载 module 会失败。

go 1.25.0 还表示当前 module 的源码使用 Go 1.25 语言版本。更新的 go1.26.4 toolchain 可以执行这次构建，但不会因此把该 module 的源码无条件当成 Go 1.26 语言进行检查。

文件级 build constraint 是一个窄例外：被 //go:build go1.26 选中的文件，可以把该文件使用的语言版本提高到 Go 1.26；但它不会降低 module 的整体最低要求，也不能绕过依赖 module 的版本约束。

go directive 还会影响 module graph 加载、Go 命令行为和部分标准库兼容默认值。所以它不只相当于一个 compiler -std 开关。

主模块的 go 版本不能低于构建列表中依赖模块的 go 版本。因此想降低一个项目的 go 行，不能只搜索自己是否使用了新语法或新标准库 API，还要检查依赖的最低 Go 要求。

5.2 toolchain 是主模块或 workspace 的开发建议下限

go 1.23.0
toolchain go1.25.4

这表达的是：

使用该 module 的消费者：至少使用 Go 1.23.0
直接维护该 main module 的开发者：建议至少使用 go1.25.4

toolchain 只在该 module 是 main module，或声明在当前 workspace 时参与工具链选择。它不会像 go directive 那样向依赖者传播。

它也不是 lock file。如果默认 toolchain 已经是 go1.26.4，toolchain go1.25.4 不会将其降级到 go1.25.4。没有显式 toolchain 行时，选择语义上存在一个与 go 行版本相同的隐含建议。

这里还有两个容易混淆的删除或固定写法：

• toolchain default 是 go.mod / go.work 中的合法 directive，表示不再根据文件中的 go / toolchain 建议切换，坚持使用 GOTOOLCHAIN 给出的默认 toolchain；如果它低于 go directive，加载仍会失败。
• go get toolchain@none 和 go work edit -toolchain=none 中的 none 是命令参数，作用是删除显式 toolchain directive；toolchain none 本身不是合法 directive。

5.3 go get 会一起维护 go 与 toolchain

Go 把 go 和 toolchain 看作当前 module 对 Go toolchain 的两项版本依赖，因此可以使用 go get 维护：

go get [email protected] [email protected]
go get toolchain@none

二者职责不同，但不是互不相干。Go 命令会维持带版本号的 toolchain 不低于 go：提高 go 越过当前 toolchain 时，后者也需要提高；二者变成相同版本时，显式 toolchain 可以删除，由 go directive 的隐含建议表达；toolchain@none 只删除显式行，不会取消 go directive 形成的最低要求和隐含建议。

所以修改这两个版本时，不要只看命令参数是否符合预期，还要检查 go.mod diff。go get 可能同时调整另一行，以恢复版本约束。

5.4 GOTOOLCHAIN 决定默认 toolchain 和自动切换策略

常见值	行为
local	固定使用当前 go 入口携带的 bundled toolchain，不自动切换
go1.25.4	固定使用该版本；PATH 中找不到时仍可下载它
auto	local+auto 的简写；必要时可从 PATH 查找或下载更新 toolchain
path	local+path 的简写；可切换，但只从 PATH 查找，不下载
go1.25.4+auto	以 go1.25.4 为默认值，必要时继续查找或下载更新 toolchain
go1.25.4+path	以 go1.25.4 为默认值，必要时只从 PATH 选择更新 toolchain

local 的含义是禁止自动切换，不是允许旧 compiler 忽略 go directive 继续构建。如果 bundled toolchain 低于模块最低要求，最终仍会拒绝加载。

GOTOOLCHAIN 的生效值依次来自当前进程环境变量、go env -w 写入的用户配置，以及 bundled toolchain 的 $GOROOT/go.env。标准发行版通常在最后一层提供 auto，但重打包版本可以改变默认值，因此应以 go env GOTOOLCHAIN 的结果为准。

Shell 上的版本管理器只决定首先启动哪个 go 入口。Go 1.21+ 内部的 toolchain selection 仍可以在此之后再次切换：

PATH / mise / Homebrew
  → 启动某个 go 入口及 bundled toolchain
    → GOTOOLCHAIN + go.work / go.mod
      → 继续使用，或从 PATH / 下载中切换到最终 toolchain

工具链切换可能发生在两个时点：

1. 启动时选择：auto / path 模式读取当前 go.work，没有 workspace 时读取主模块的 go.mod，再结合默认 toolchain、go 和 toolchain directive 选择足够新的版本。
2. 执行中切换：go get、go install package@version 等命令可能在加载新 module 后，才发现更高的 go 要求。允许切换时，Go 会从受支持候选中选择满足要求的版本，并可能把新要求写回 go.mod / go.work。

这也解释了为什么“取 GOTOOLCHAIN、go、toolchain 三者最大值”只是一种近似记忆。fixed 模式、toolchain default、workspace 覆盖、PATH 可用性和执行中才发现的新要求，都会改变真实流程。

5.5 下载得到的 toolchain 也是 module

auto 允许下载时，Go 不会借助另一个独立安装器，而是把 toolchain 包装成特殊 module：

golang.org/[email protected]

它通过 GOPROXY 获取，解压到 $GOMODCACHE，由 Go checksum database 验证。由于 toolchain checksum 不写入项目 go.sum，下载时必须能够访问 checksum database；GOSUMDB=off 会使正常的自动下载失败，GONOSUMDB / GOPRIVATE 也不能把 toolchain 排除在验证之外。

因此开发机上自动切换成功，不代表隔离网络中的 CI 一定成功。CI 要明确选择一种供应策略：预装固定版本；在 PATH 中提供候选并使用 +path；或者保证 GOPROXY 与 checksum database 链路可用。

下载后，下面两个事实可能同时成立：

which go       → 最初启动的 go 入口
go env GOROOT  → module cache 中最终 toolchain 的目录

这不是路径冲突，而是入口工具完成了二次选择。

5.6 配置不是运行事实

可以用下面的命令逐层核对：

which go
go env GOMOD GOWORK
go env GOTOOLCHAIN
GOTOOLCHAIN=local go version
go version
go env GOROOT

• which go 说明 Shell 选中的入口；
• GOTOOLCHAIN=local go version 显示该入口携带的 bundled toolchain；
• 正常执行的 go version 显示当前命令最终选中的 toolchain；
• go env GOROOT 显示最终 toolchain 实际从哪个目录提供 compiler、linker 和标准库。

Go 1.24 起还可查看工具链选择轨迹：

GODEBUG=toolchaintrace=1 go version

一次 go build、go test 或 go generate 最终使用一套 toolchain，但这不表示整个仓库永远只能涉及一个 Go 版本。CI 矩阵、独立命令、多 module 仓库和代码生成器都可以分别启动自己的工具链选择流程。

可以用一个不带内部项目背景的例子串起这条链路：

go.mod: go 1.25.0，没有显式 toolchain
本机入口携带: go1.26.4
GOTOOLCHAIN: auto

这里隐含建议是 go1.25.0，但默认候选 go1.26.4 已经更新，因此 Go 不会降级或下载，最终继续使用 go1.26.4。当前 module 的源码仍按 Go 1.25 语言版本处理。由此只能证明“本机现有 toolchain 满足要求”，不能证明项目也兼容 Go 1.24，更不能说明 go 1.25.0 已被 go1.26.4 覆盖。

6. internal 是基于 import path 和目录树的可见性边界

internal 不表示“私有 Git 仓库”、“不对外发布的 module”或 Java 式的 package-private。它是 Go 命令基于 package import path 与源码目录位置强制的导入规则。

官方规则是：位于名为 internal 的目录之内或之下的 package，只能被位于该 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 不满足。

所以导入失败。实践中可以从目标 import path 最右侧的 internal 开始检查；只要任意一层不满足，整个 import 就不合法。

7. 用分层问题排查 Go 工具链

遇到 Go 命令行为与预期不一致时，不要先把所有现象归因于“版本问题”或“依赖问题”。按下面的顺序逐层确认。

7.1 工具链选择与供应层

which go
go env GOMOD GOWORK GOTOOLCHAIN GOROOT
GOTOOLCHAIN=local go version
go version
GODEBUG=toolchaintrace=1 go version
go env GOPROXY GOSUMDB GOMODCACHE

回答：Shell 启动了谁，最终又由谁执行？如果需要切换，候选 toolchain 来自 PATH 还是下载，代理、checksum database 和 module cache 是否可用？

7.2 命令行选择层

pwd

go list -f '{{.ImportPath}} {{.Dir}}' ./cmd/server

go list ./...

回答：参数相对哪个目录解析，实际选中哪些 package？

7.3 package 加载层

go list -deps -json ./cmd/server
go build -x ./cmd/server
go build -work -x ./cmd/server

回答：实际选中哪些源文件，package import graph 是什么，compiler invocation 是什么？

7.4 module 供应层

go list -m -json all
go mod graph
go mod why -m example.com/module

go list -m -f '{{if .GoVersion}}{{.Path}} {{.Version}} go={{.GoVersion}}{{end}}' all

回答：每个 import path 由哪个 module version 提供，版本要求从哪里进入 module graph，各依赖 module 又声明了怎样的最低 Go 版本？

7.5 可见性和语言版本层

回答：是否触发 internal 等导入限制？当前 package 所属 module 的 go directive 是什么？实际 compile 命令使用了哪个 -lang=go1.N？

7.6 构建产物事实层

go version -m /path/to/binary

回答：目标二进制由哪个 Go 版本构建，记录了哪些 module 信息？二进制启动时不会重新执行 GOTOOLCHAIN 选择，因此线上事实要从产物本身确认，不能从当前开发机的 go version 反推。

这套顺序的价值在于，它会阻止下面这些跨层推断：

• 看到命令行上是目录样式，就认为 Go 没有处理 package；
• 看到 package import chain 和 module 错误相邻，就认为它们在源码上直接依赖；
• 看到 go 1.25.0，就认为实际 compiler 一定是 go1.25.0；
• 看到 toolchain go1.25.4，就认为开发机会被精确锁定到 go1.25.4。

8. 复习索引

• package 是编译和 import 的逻辑单元；目录是常规的存放与定位方式。
• package name 是源码中的本地名字；import path 是 package 在程序中的唯一身份。
• 主模块内 package import path 通常是 module path + 相对 module 根的子目录。
• 命令行 ./cmd/server 相对当前工作目录定位 package，不是源码中使用的 import path，也不默认相对 module 根。
• ... 是 Go package pattern wildcard，可以匹配空串和包含 / 的字符串；./... 从当前工作目录子树开始匹配。
• go build 的构建颗粒度始终是 package；go build ./pkg 定位已有 package，go build a.go b.go 则用具名文件合成伪 import path 为 command-line-arguments 的临时 package。
• 默认只有单个 main package 写出可执行文件；多个 package 或单个非 main package 只检查可构建性；-o 覆盖输出规则。
• package graph 的边来自源码 import；module graph 的边来自各版本 go.mod 的 require。
• MVS 对同一 module path 选择构建列表中已提出的最高版本。
• go 1.N.P 声明 module 最低 Go 版本，并以 1.N 为语言版本；它还影响 module 和兼容行为。
• toolchain go1.N.P 是 main module / workspace 的建议 toolchain 下限，不精确锁版，不向依赖者传播。
• go get 会把 go 与 toolchain 当作两项有关联的版本依赖共同维护；toolchain@none 只删除显式建议。
• GOTOOLCHAIN 决定默认 toolchain 和是否允许从 PATH 查找或下载；选择既可能发生在启动时，也可能发生在命令加载新 module 之后。
• 下载的 toolchain 是 golang.org/toolchain 特殊 module，进入 $GOMODCACHE，依赖 GOPROXY 和 checksum database，但不写项目 go.sum。
• which go 只说明启动入口；go version、GOROOT、toolchain trace 和构建产物才是对应阶段的运行事实。
• internal 使用其父目录树限制 import 方；目标 import path 中的每一层 internal 都必须满足。

9. 核验入口

• Go command documentation
• Package lists and patterns
• Go Modules Reference
• Go Toolchains
• Go 1.26 cmd/go package loader