Go go mod tidy 结果不稳定怎么办

go mod tidy 在本地和 CI 反复产生不同结果，先固定同一份源码、同一个模块目录和实际运行的 Go 工具链，再看变化来自 go.mod 还是 go.sum。tidy 根据源码中的依赖整理模块文件，不是只整理当前平台能编译的主程序，也不是每次把全部依赖升级到最新版。

一个典型排查场景是：开发者提交整理后的文件，CI 又要求修改，拉回本地再次运行却改回去了。不要立即删除 go.sum 或清空模块缓存；这会增加下载和解析变量。应先保留差异，把“输入发生变化”和“相同输入重复产生变化”分开处理。下面的命令供读者在自己的仓库执行，本文没有运行记录或故障复现声明。

官方文档：https://go.dev/ref/mod#go-mod-tidy

先区分文件差异与命令失败

“结果不稳定”至少有三种含义：命令成功但文件不同；命令在另一台机器下载失败；命令第一次有改动、之后不再改动。第一种要比较依赖输入，第二种要看具体下载或认证错误，第三种通常是文件尚未与源码同步，不能仅凭首次改动判定不稳定。

如果所用工具链支持 tidy -diff，可先查看所需修改而不写入 go.mod、go.sum。它有差异时会以非零状态退出，因此 CI 中的非零状态也可能表示文件待整理，需要结合输出内容解释；下载、缓存和工具链选择等活动仍可能发生。

# 查看当前仓库状态，先保留已有修改。
git status --short
# 显示模块文件需要的改动，不写回这两个文件。
go mod tidy -diff

固定实际工具链和模块目录

先在开发机与 CI 相同的工作目录记录下列信息。Go 支持根据 GOTOOLCHAIN 与模块或工作区声明选择工具链，因此仅检查 PATH 里的启动程序不够。相同工具链策略，也不代表实际选中的补丁版本一定相同。

# 在目标模块目录记录实际使用的工具链版本。
go version
# 确认模块文件与工作区文件来自哪里。
go env GOMOD GOWORK GOTOOLCHAIN GOFLAGS
# 记录源码基线，同时保留未提交与未跟踪文件情况。
git rev-parse HEAD
git status --short

这些输出可能包含本机路径或项目内部信息，协作时按需脱敏。核对 go.mod 的 go、toolchain、replace、exclude，以及适用时的 go.work。尤其是本地 replace 指向另一份源码时，即使当前仓库提交相同，被替换模块的内容也可能不同。

不要为了让 diff 消失而随意降低 go 行。它声明模块的最低 Go 版本要求，还关联依赖图整理规则。统一工具链应使用项目已确认支持的具体版本，并把升级当成单独变更评审；不能只在某台机器上用持久化 go env -w 修改后就认为团队已经统一。

检查测试与构建标签隐藏的依赖

tidy 的扫描范围大于一次当前平台的普通构建。测试源码、平台专用文件、自定义构建标签文件都可能引入需要整理的依赖；ignore 标签是特殊例外。模块中声明的工具依赖也要纳入考虑，具体能力以所用工具链为准。

例如，业务目录没有新增导入，但另一个测试文件引用了断言库，或者某个平台专用适配器增加了客户端包，tidy 就可能更新模块声明。仅比较主程序 import 列表会漏掉原因。对于生成代码，确认两端是否都已生成、是否使用同一生成器版本，以及生成物是否应提交；未跟踪的 Go 文件同样值得检查。

不能仅通过切换 GOOS、GOARCH 或删掉某个 -tags 参数，期待 tidy 丢弃其他平台或标签的依赖。它不是面向当前部署目标裁剪模块的命令。若一个工具已不再使用，应移除真实引用或相应工具声明，再整理模块文件，而不是只手动删除 require。

定位 go.mod 和 go.sum 变化的来源

拿到一条新 require 后，先找哪个包使用了它，再看依赖关系。下面命令中的模块路径只是占位示例，必须替换成 diff 里实际出现的模块；不要原样执行一个不存在的示例路径并据此判断问题。

# 把示例路径换成实际模块，查看需要它的包导入关系。
go mod why -m example.com/team/dependency
# 辅助查看模块之间的最低版本要求。
go mod graph
# 在允许写回的维护环节整理，并报告删除的模块。
go mod tidy -v
# 仅查看模块文件改动，保留业务源码的其他修改。
git diff -- go.mod go.sum

why 解释包的使用链，graph 展示模块要求关系，两者回答的问题不同。它们也不是 tidy 全部扫描范围的等价替身，遇到只在特定标签下出现的引用仍需回到相应源码。不要因为一次普通构建没用到某包，就删除其模块声明。

go.sum 记录校验和，不是简单的“当前直接依赖清单”。同一模块的版本元数据和内容可能分别留下条目；旧版本校验和是否保留也与兼容需求有关。-compat 控制的是模块图兼容检查范围，-go 会更新 go 声明并影响图规则，它们都不是无副作用的格式参数。

另一个值得区分的情况是源码新增了尚未被模块图提供的包。tidy 需要解析缺失模块，可能选择当时符合查询规则的版本；若两端在不同时间从不完整的模块声明起步，外部可用版本就成了变量。选定依赖后提交整理后的 go.mod 与 go.sum，而不是让每次 CI 从缺失声明重新解析。已有明确要求的模块不会因为 tidy 就统一升级到最新版本。

固定团队维护方式并判断重复结果

可把依赖维护分成两个明确入口：开发者在固定工具链中整理并提交，CI 在相同上下文中确认提交内容是否仍需整理。工具链、源码、替换目标和初始模块文件保持一致时，第一次整理后再运行不应持续制造新的同类差异；若仍交替变化，要继续寻找编辑器自动任务、并发脚本或生成器是否改写了文件。

# 在已保存工作的目标模块中完成一次依赖整理。
go mod tidy
# 紧接着查看是否还有未落实的整理差异，需工具链支持。
go mod tidy -diff
# 对照改动来源；这些命令未在本文制作过程中执行。
git diff -- go.mod go.sum

这里的成功标准是“第二次不再提出新整理”，不等于 git diff 必须为空：第一次整理产生但尚未提交的修改仍会显示。CI 从已提交基线检查时则应没有待整理差异。把这两种判定混在一起，很容易把一次正常维护误报成循环修改。

固定版本有维护成本：需要按计划升级工具链和依赖，并处理最低版本要求变化。它的价值在于让每次差异可解释，不能代替升级工作。也不要在同一模块目录同时运行两个版本的 tidy；两个写入者交替保存会让定位结果失去意义。

处理工作区与常见误区

多模块仓库不能在仓库根目录运行一次 tidy，就假定所有模块都已整理。tidy 针对单个主模块；应明确进入哪个模块、使用哪些替换内容。若单独模块在工作区外仍需可构建，应另外检查其独立依赖是否声明完整，不能依赖其他工作区模块掩盖缺口。

有 vendor 就能避免 tidy 联网吗？

不能这样推断。tidy 仍可能下载模块并使用模块缓存，vendor 的构建使用规则不等于 tidy 的依赖整理规则。按项目要求维护 vendor，应在依赖更新后另行同步。

删除 go.sum 重新生成是不是最快？

通常不适合作为第一步。先保留原始差异并找出变化原因；删除文件会丢失用于比较的信息，也不能修复工具链或源码不同的问题。

加 -e 能让整理结果更可靠吗？

-e 允许在包加载出错时尝试继续，不代表错误消失。排查结果差异时，应先处理加载失败，不能把存在错误时生成的文件当成稳定基线。

工具链官方说明：https://go.dev/doc/toolchain。把实际工具链、模块输入和文件职责分别对齐，才能判断剩下的差异是否属于真正的重复整理问题。