go mod tidy 是 Go 官方推荐的唯一可靠自动清理未使用依赖方式，基于 go.mod 与源码 import 的双向比对同步增删依赖，但空白导入、条件编译、运行时加载及手动 require 等情况会导致“该删没删”，需配合验证与参数优化。
go mod tidy 是 Go 官方推荐的、唯一可靠的自动清理未使用依赖的方式。它不会“只删未用包”，而是基于 go.mod 和源码中实际 import 语句的双向比对，同步增删依赖项——也就是说：删得准，但前提是你没漏写 import，也没在运行时靠字符串加载包（比如插件、反射调用）。
为什么 go mod tidy 有时不删包？常见原因
它不是“扫描代码然后删掉没 import 的包”，而是执行两步操作：先下载所有 import 到的包并记录到 go.mod；再移除 go.mod 中存在、但当前模块里没有任何 import 语句引用的包（及其间接依赖）。所以以下情况会导致“该删没删”：
- 代码里用了
import _ "github.com/some/pkg"（空白导入），go mod tidy会认为这个包被显式需要，不会删 - 包被
//go:embed或//go:build条件编译标记间接依赖，但主干代码没 import ——tidy默认不分析这些，除非你加-compat=1.21+（Go 1.21+ 支持更严格的构建约束解析） - 运行时通过
plugin.Open()或reflect.ImportPath加载包，这类依赖无法静态识别，tidy必然忽略 -
go.mod里手动写了require但没对应 import，且该包是其他已用包的旧版间接依赖（比如 A → B v1.0，你又手动 require B v2.0），tidy可能保留 v2.0 以防冲突，需配合go mod graph | grep检查
安全清理前必须做的三件事
盲目跑 go mod tidy 可能导致构建失败或运行时 panic，尤其在有测试、生成代码、跨平台构建的项目中：
- 确保所有
.go文件（包括_test.go、main.go、gen.go）都已保存，且go build ./...和go test ./...全部通过 - 检查是否有代码生成逻辑（如
stringer、mockgen、protoc-gen-go），它们可能 import 了你源码里没写的包——先运行生成命令，再 tidy - 如果项目支持多平台（如含
GOOS=js或GOARCH=wasm构建），建议先用对应环境执行一次GOOS=xxx GOARCH=yyy go list -deps ./... | grep看是否引入额外包，再决定是否在 tidy 后手动go mod edit -droprequire
go mod tidy 的实用参数组合
默认行为足够大多数场景，但遇到复杂依赖树时，这几个参数能帮你更快定位问题：
立即学习“go语言免费学习笔记（深入）”；
-
go mod tidy -v：输出每一步增删的包名和版本，方便确认是否误删关键依赖 -
go mod tidy -compat=1.21（Go 1.21+）：启用更严格的构建约束解析，能识别部分条件编译下的隐式依赖 -
go mod tidy -e：即使遇到错误（比如某依赖无法下载）也继续处理其余部分，适合临时网络不稳定时快速清理主干依赖 - 想只看变化不执行？用
go mod tidy -dry-run（Go 1.22+），它会打印将要添加/删除的行，但不动go.mod和go.sum
真正容易被忽略的点是：当你在 internal/ 子模块里新增了一个 import，但忘了 go mod tidy，后续别人拉代码就会 go build 失败——因为 go.mod 没更新，CI 也没法自动补。所以最佳实践是把 go mod tidy 写进 pre-commit hook 或 CI 的 lint 阶段，而不是等出问题再手动救火。
