Go go1.27 go mod tidy 后 require 块为什么被重新整理

Go 1.27 中，如果模块的 go.mod 声明 go 1.27 或更高版本，go mod tidy 会主动合并零散的 require 块，使文件最多保留两类块：直接依赖与间接依赖。原先手工分出的几个块被合并，通常是这项整理规则起作用；但 tidy 还可能增删依赖、调整 indirect 标记，所以不能只凭“位置变了”就断定没有语义变化。

我会先看模块版本而不是块的位置

遇到“刚执行 tidy，require 块怎么不见了”的 diff，我会先把注意力放到 go 指令，再看具体依赖条目。这里说的是排查取舍，不是声称发生过某次线上事故，也不把下面的示意当作实测结果。Go 1.27 官方发布说明明确把新整理行为限定到模块声明的版本；不是只看电脑上安装了哪个 Go，就推断所有老模块都会按同样规则改写。

Go 官方地址：https://go.dev/

具体规则见 Go 1.27 发布说明的 go mod tidy 小节。我不建议为了保住人工排版而随意降低 go 行：它还代表模块最低 Go 版本等含义，不是专门控制缩进和分组的开关。

把 diff 分成三类再判断

我会把第一类与后两类分开审阅。这样既不会把一次正常的块合并误判为升级依赖，也不会因为“tidy 本来就会格式化”而漏掉实际版本变化。尤其是 go.sum 的增删，不应直接当作某个 require 版本已经升级的证明。

从工具链与模块范围找线索

先确认当前目录、实际模块文件和有效工具链。以下命令供读者在自己的仓库中使用，本文没有执行这些命令。不要先手改 require 块，再比较改写结果，否则容易把原始线索覆盖。

# 查看实际运行的 Go 版本及模块、工作区位置。
go version
go env GOMOD GOWORK GOTOOLCHAIN

# 只读输出当前模块文件的结构化内容，不修改 go.mod。
go mod edit -json

# 先区分模块元数据中哪些行发生了变化。
git diff -- go.mod go.sum

GOMOD 帮助确认有没有在错误的目录整理另一个模块，GOWORK 提醒当前是否处于工作区。go mod tidy 的作用对象仍是相应模块，不应把一个模块的 tidy 当成工作区所有模块同时整理。若有人设置了 -modfile 或其他环境选项，也应把这类参数纳入复现记录。

需要强调，我会区分“工具链版本”和“go.mod 的 go 指令”：前者决定执行命令的工具实现，后者是发布说明中新合并规则的适用条件。toolchain 指令与工具链自动选择也不能简单等同于把 go 指令提高到 1.27。排查时把两者写清，比讨论“我本地已经升级了”更有帮助。

多块为什么会合成两类

假设依赖集合和直接性都不变，原文件为了视觉分区放了三段 require：两个直接依赖分别占一块，另外一个间接依赖单独占块。Go 1.27 新规则会把直接依赖归并到同类块中，间接依赖放在另一类块。下面只演示文件形状，example.com 路径都是占位符，不是建议安装的真实模块；也没有相应源码可用于执行 tidy。

module example.com/team/report

go 1.27.0

// 以下为形状示意，不是可运行依赖清单。
require example.com/lib/alpha v1.2.0

require example.com/lib/beta v1.4.0

require example.com/lib/helper v1.1.0 // indirect

在条目仍被同样需要的前提下，直接与间接依赖可以整理为下面的结构。这个示意刻意不模拟注释块迁移的精确位置，实际注释按工具规则保留。

module example.com/team/report

go 1.27.0

// 直接依赖合并示意：路径和版本保持不变。
require (
    example.com/lib/alpha v1.2.0
    example.com/lib/beta v1.4.0
)

// 间接依赖单独成类；原始文件未必恰好使用这组注释。
require example.com/lib/helper v1.1.0 // indirect

附着在依赖上的原有注释块会被保留。按照发布说明，如果一组注释原先关联了混合的直接与间接指令，该注释块会合并并附到新的直接依赖块。因而注释挪动不应立刻解释成内容被删除；也不应把注释中人工描述的“分组”当成 Go 模块解析语义。

与此同时，tidy 的常规工作并未变成“只合并括号”。模块参考文档说明，它会根据包加载需要补充、移除模块要求及校验和，也会调整 indirect 标记；测试、工具和平台相关源码都可能影响所需集合，构建标签处理并不等同于一次普通本机编译。不要因为一个包只在测试或另一平台源码中出现，就手工删除其依赖。

团队怎样接纳这次整理

我的取舍是让模块文件交给统一工具生成，而不是长期维持容易被覆盖的手工块布局。适合把“工具链与模块版本变更”“纯结构整理”“真实依赖变更”拆开提交的团队，可以先集中处理一次正常化差异，再让后续依赖变更保持清晰。小仓库也可以同一提交处理，但提交说明要把语义变化讲清楚。

开发机、CI 和依赖更新机器人应使用团队约定的 Go 版本及相同参数。仅固定编辑器版本不够，也不要靠额外脚本在每次 tidy 后把 require 又拆回三四块。那会产生工具改一遍、脚本改回去的反复 diff，掩盖真正需要审阅的条目。

如果出现非预期新增模块或版本变化，应回到包导入、工具声明和模块约束寻找原因；不要单靠回退括号布局来“修复”。也不应为了追求一次零 diff 就盲目使用 -e 忽略包加载错误。先解决加载失败，才能解释 tidy 依据的输入。

复查时看依赖内容而非原排版

读者在自己的开发流程中可先预览整理差异，再决定是否写回。下面是排查文章提供的操作示例，未在本轮文章生产中运行，也不是对当前发布包增加检查阶段。

# 只展示 go.mod 和 go.sum 所需差异，不改写这两个文件。
go mod tidy -diff

# 已确认差异并决定采纳后，再正式更新模块元数据。
go mod tidy

# 查看实际更新内容，版本变化应单独说明原因。
git diff -- go.mod go.sum

-diff 有差异时会返回非零退出码，这不等于必然出现网络故障或语法错误；应结合输出区分原因。它不会写回 go.mod 和 go.sum，但包加载仍可能需要下载模块或写入缓存，因此不是完全无网络、无其他副作用的命令。涉及私有模块时沿用既有访问策略，切勿把凭据写进排障记录。

安装 Go 1.27 就一定合并老模块的 require 吗？

不能这样概括。新合并规则的说明明确对应 go.mod 声明 go 1.27 或更高版本的模块，同时还应确认实际执行的工具链。

两个块一定都存在吗？

不是。规则是最多两类块；没有对应依赖类别就不必为了视觉统一造一个空块。

indirect 是否表示这个依赖可以删掉？

不是。它说明与主模块包导入的关系，间接依赖仍可能是构建所需模块图的一部分。

我最终会问的是“模块路径、版本和直接性发生了什么”，而不是“原来那几个括号还在不在”。Go 1.27 的 require 整理让结构更统一；把这项变化和 tidy 的依赖维护职责分开理解，才更容易判断一次 diff 是否正常。