Go 1.27 的 go mod tidy 会把重复 require 块合并成两块

面向 go.mod 里 go 指令 ≥ 1.27 的模块，go mod tidy 现在会自动合并重复的 require 块，把文件收敛到标准结构：最多两个 require 块，一个直接依赖、一个间接依赖。低于 1.27 的模块不受影响。

参考：Go 1.27 Release Notes（https://go.dev/doc/go1.27）。

require 块合并规则

• 触发条件：go.mod 的 go 指令为 1.27 或更高。
• 依赖上附带的注释块在合并时保留。如果一个注释块关联的是直接 + 间接混合的 directives，注释块会被合并并挂到新的直接依赖块上。
• 此前如果 go.mod 累积了多个互不相连的 require 块（常见于手动编辑、未解决的 Git 合并冲突、遗留升级），go mod tidy 会保留多余块，甚至无意中新建块。现在工具严格强制两块布局。

该行为对应的提案 Issue 是 cmd/go: mod tidy should join "require" sections if there are more than two #56471，2022 年提起，约 4 年；实现为 CL 738740。

以前为什么会增殖

go mod edit -require 会把新依赖无条件追加到最后一个块，于是直接依赖混进 // indirect 块。之后 tidy（go1.26.5）找不到「纯直接块」和「纯间接块」，就会为新增的间接依赖（例如 cobra 引出的 pflag、mousetrap）新建第三个块；再跑一次 tidy 也稳定在 3 块。相关报障 Issue：go: 'mod tidy' sometimes adds new, unnecessary require sections #67948。

升级注意

go mod tidy 只做布局整理，不等于升级依赖版本。要升级用 go get module@version，再 tidy。

核对流程：

go version
git diff -- go.mod go.sum
go mod tidy
git diff --stat -- go.mod go.sum
go list -m all > /tmp/modules-go127.txt

diff 里各类变化的含义：

• require 块位置变化 = 工具链整理布局。
• go.sum 新增校验和 = 新构建路径 / 新模块版本，跑 go mod verify。
• 直接依赖变 indirect = 代码不再直接 import，搜 import 并查生成代码与构建标签。
• 模块版本升高 = 显式升级 / MVS / 工具链差异，比较 go list -m all 快照。

纯布局 diff 单独提交。

go doc 增强

go doc 现在支持 package@version 语法，例如：

go doc example.com/pkg@v1.2.3

可以直接看某个具体版本的文档，不必先切换依赖版本。

go doc 新增 -ex 选项，列出某包或符号的可执行示例；当在命令行传示例名（如 go doc bytes.ExampleBuffer），会连同注释打印示例源码。

go fix modernizers 变动

新增四个 modernizers：atomictypes、embedlit、slicesbackward、unsafefuncs；移除了 fmtappendf 分析器，并把 waitgroup 分析器改名为 waitgroupgo。

其他

• 小对象分配提速约 30%（size-specialized 内存分配）。
• goroutineleak profile GA。
• 新增 encoding/json/v2。
• 新增 crypto/mldsa。
• 新增 uuid 标准库。
• 新增 simd 实验包。