go mod tidy 是让 go.mod 与源码 import 严格同步的命令：添加缺失依赖、移除未引用模块（含孤儿间接依赖），确保依赖最小化且可复现；它默认升级间接依赖、重生成 go.sum，受 replace/exclude 影响，不处理 vendor。
go mod tidy 是什么，它到底在做什么
go mod tidy 不是简单地“下载缺失包”或“清理无用依赖”，而是让 go.mod 文件与当前模块的源码（.go 文件）严格同步：它会添加源码中 import 但未出现在 go.mod 中的依赖，同时移除 go.mod 中存在、但源码里已不再引用的模块（包括间接依赖中的“孤儿”项）。它的目标是让模块定义可复现且最小化。
什么时候必须运行 go mod tidy
以下场景不手动执行，大概率导致构建失败或依赖混乱：
- 新增了
import "github.com/some/pkg"，但没手动go get - 删掉了某个
import，但go.mod还留着对应条目（尤其容易发生在重构后） - 升级主依赖（如
go get example.com/lib@v1.2.0）后，其新版本引入了新子依赖，旧版go.sum校验会失败 - CI/CD 流水线中，必须确保每次构建前依赖状态干净——建议固定加在构建脚本开头
go mod tidy 的常见副作用和坑
它看似安全，但几个行为常被忽略：
- 默认会升级间接依赖到满足所有直接依赖的**最新兼容版本**（比如
golang.org/x/net可能从 v0.7.0 升到 v0.25.0），可能引入不兼容变更 - 如果本地
go.sum缺失或损坏，tidy会重新生成，但不会校验已有 checksum 是否匹配远程——可能导致静默替换 - 对
replace和exclude指令敏感：若replace指向本地路径，而该路径下没有go.mod，tidy会报错退出 - 不处理 vendor 目录：即使你启用了
GO111MODULE=on+go mod vendor，tidy仍只操作go.mod和go.sum
如何控制 go mod tidy 的行为
它支持有限但关键的参数，日常够用：
立即学习“go语言免费学习笔记（深入）”；
-
go mod tidy -v：显示每一步操作（添加/删除哪个模块），适合调试依赖变化 -
go mod tidy -compat=1.21：强制使用 Go 1.21 兼容模式解析模块（影响go.mod文件头声明和语义版本解析逻辑） - 想跳过某些模块？不行——
tidy不接受--exclude。如需保留某依赖，只能在源码里保留一个 dummy import，或改用go get+go mod edit -require手动写入 - CI 中推荐加
-e（遇到错误立即退出）+-v，避免静默失败
真正麻烦的是跨团队协作时：A 同学 go mod tidy 后提交了 go.mod，B 同学拉下来却因 GOproxy 配置不同，触发了不同版本解析路径——最终 go.sum 行数不一致。这不是命令的问题，而是环境没对齐。