goModTidy清理模块需求

如果项目里的 go.mod 越积越长，go.sum 也出现一批已经不用的校验记录，通常先想到的就是 go mod tidy。它的职责不是“把所有依赖升级到最新版”，而是让模块文件与当前源码实际加载到的包保持一致：补上缺失需求，删除不再提供相关包的模块，并同步整理 go.sum。

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

安全的使用方式是先在包含 go.mod 的模块根目录执行 go mod tidy -diff 预览差异；确认变更符合预期后，再执行 go mod tidy 写回文件。它整理的是依赖关系，不等于升级依赖版本。

go mod tidy 到底会清理什么

tidy 会按模块中的包、这些包导入的依赖，以及测试和构建约束所覆盖到的包来整理需求。它可以在 go.mod 中添加构建当前模块所需但尚未声明的模块，也会移除不再提供相关包的 require 项，同时补齐或删除 go.sum 中不需要的校验记录。

因此，清理结果不只取决于生产代码。测试文件、平台专用文件和非 ignore 构建标签都可能影响依赖集合；目录名以点号或下划线开头、以及 testdata 中的包通常不会被主动加载，除非它们被其他包明确导入。

最小命令：让模块文件匹配源码

在模块根目录执行下面的命令即可开始整理。命令不需要指定某个模块名，因为它会以当前模块为范围读取包和依赖。

# 在包含 go.mod 的模块根目录整理 go.mod 与 go.sum
go mod tidy

# 输出被移除的模块，适合快速了解清理原因
go mod tidy -v

# 只打印需要写入的统一差异，不直接修改模块文件
go mod tidy -diff

-diff 是提交前很实用的观察入口：如果没有差异，说明当前文件已经与 tidy 看到的依赖集合一致；如果有差异，先阅读新增、删除和 // indirect 注释的变化，再决定是否写回。-v 只增强输出信息，不改变 tidy 的清理目标。

为什么 tidy 会带入测试依赖

很多“明明生产代码没导入，为什么 go.mod 多了一项”的疑问，来源都是测试。go mod tidy 会加载主模块的包、工具以及它们递归导入的包，也会考虑主模块中测试文件的依赖；所以一个只在 _test.go 使用的测试库，可能仍然需要留在模块需求中。

# 先预览整个模块的整理结果，避免直接覆盖文件
go mod tidy -diff

# 如果只想观察某个包的依赖，不要用 tidy 代替包级查询
go list -deps -json ./internal/feature

# 打印当前构建列表中的模块，辅助确认最终模块集合
go list -m all

这里要分清工具职责：go list 用来观察包或模块，go mod tidy 用来把观察到的依赖需求写回模块文件。不要因为 tidy 产生了测试依赖，就直接删除它；应该先确认对应测试是否仍然存在，以及构建标签是否让某个文件参与加载。

用 -compat 控制兼容性检查

在较新的 Go 工具链中，tidy 默认会检查前一个 Go 版本加载模块图时是否会得到不同的选中版本。需要明确兼容目标时，可以使用 -compat；它会保留目标版本所需的额外校验，并在该版本会加载到不同模块版本时报告错误。

# 以项目声明的 go 版本前一个主要版本做兼容检查
go mod tidy -compat=1.23

# 只比较差异，不把兼容检查结果写回 go.mod 或 go.sum
go mod tidy -compat=1.23 -diff

-compat 不是把当前工程切换到指定 Go 版本，也不会替你完成依赖升级；它约束的是模块图加载和校验的兼容检查。实际版本应以项目的构建矩阵和 go 指令为准，不要为了让命令通过而随意填写一个版本号。

tidy、get、vendor 和 verify 不要混用

比较稳妥的提交前习惯是：先用 go mod tidy -diff 看变更，再根据团队约定执行 tidy 写回；如果项目提交 vendor，再单独运行 go mod vendor；如果需要确认缓存完整性，再使用 go mod verify。每个命令解决的是不同层次的问题。

相关问题

go mod tidy 会自动升级依赖吗？

它可能为缺失模块选择可用版本，但它的核心目标是让需求与源码匹配，不是对已有依赖做全面升级。明确升级应使用 go get 模块@版本，之后再 tidy。

为什么执行 tidy 后 go.sum 仍然有很多行？

go.sum 保存模块内容和模块文件的校验信息，当前模块图或兼容检查仍需要的记录会保留；“变少”不是 tidy 成功的唯一标准。