go mod tidy是Go官方唯一能同时删除冗余依赖、补全缺失依赖并同步更新go.sum的命令，它不升级版本、不修改模块路径、默认不触碰vendor目录（除非加-v参数），前提是所有import语句均为静态可分析。
go mod tidy 是唯一能同时删冗余、补缺失、同步校验和的官方命令，它不升级版本、不改主路径、不碰 vendor（除非加 -v），但前提是你的 import 是静态可分析的。
什么时候该直接运行 go mod tidy
你刚删掉一段 import，但 go.mod 里还留着对应 require 行；或者克隆完一个项目，go build 报 cannot find package；又或者想确认当前依赖是否最小化。这些场景下，进项目根目录（含 go.mod 的目录）直接执行：
go mod tidy
它会立刻做三件事：
- 扫描所有
.go文件（包括*_test.go和main.go），提取全部import路径 - 对比
go.mod中的require列表，移除未被任何import引用、且不是其他依赖传递链一环的模块 - 把代码中用了但
go.mod没记录的包自动加进去，并更新go.sum
为什么 go mod tidy 没删掉某个模块？
它不是“看名字觉得没用就删”，而是严格按导入图裁剪。以下情况会让模块被保留：
- 代码里有
import _ "github.com/some/pkg"（空白导入），tidy认为这是显式需要 - 模块被
//go:embed或//go:build条件编译代码间接引用，而你没在对应构建环境下运行tidy - 另一个已用依赖的
go.mod里require了它（比如 A → B v1.2.0，B 自己 require C，那 C 就算你没直接 import 也会留下） -
go.mod里手动写了replace或exclude，tidy仍按图计算，但不会主动提醒规则是否已失效
验证真实依赖链，用：go mod graph | grep your-module-name
清理后编译失败，优先检查这三类残留
go mod tidy 本身不引入 bug，但它会暴露原本被冗余依赖掩盖的问题：
-
go.mod里还有replace指向本地路径，但对应目录已被删或重命名 - 测试文件（
*_test.go）里用了某包，但你运行tidy前没跑go test ./，导致生成代码或 mock 依赖未被识别 - 项目含多模块（子目录有独立
go.mod），你在根目录执行tidy，结果把子模块的依赖错误合并或清掉了
修复方法：进对应子目录单独执行 go mod tidy，或临时删掉 go.work 避免工作区干扰。
要不要加 -v 或 -compat 参数？
日常清理不需要，但遇到问题时它们是关键线索：
-
go mod tidy -v：输出每一步决策，比如removing unused module github.com/xxx或adding implicit dependency，帮你确认删得对不对 -
go mod tidy -compat=1.21：强制启用 Go 1.21+ 的构建约束解析逻辑，对含复杂//go:build的项目更准 - 别用
go mod tidy -v配合vendor—— 真要更新vendor/，得明确加-v参数，否则vendor/不会变，CI 可能报cannot find package
真正容易被忽略的是：它从不清理 $GOPATH/pkg/mod 缓存，旧版本模块还在磁盘上占空间；要彻底释放，得额外跑 go clean -modcache，但这会拖慢下次构建 —— 所以只在换机器、CI 初始化或磁盘告警时才用。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
