go mod tidy 只删除完全未被 import 的模块，保留间接引用、//go:embed、//go:build 等隐式依赖；需用 go mod graph 分析真实依赖，-v 参数同步 vendor，goproxy/goprivate 配置影响速度，checksum mismatch 应先验证再清理 go.sum。
go mod tidy 为什么没删掉某些模块
它只删「完全没被 import 的模块」，不是删「看起来没用的模块」。比如模块里某个 submodule 被间接引用（通过其他依赖的 go.mod 声明），或者项目里有未执行的 //go:embed、//go:build 条件编译代码，go mod tidy 都会保留对应模块。
常见错误现象：go mod graph | grep xxx 发现某模块还在依赖图里，但自己代码里根本没写 import —— 很可能它是被某个依赖的 go.mod 显式 require 的，或被 replace 规则间接拉进来的。
- 运行
go mod graph查看实际依赖流向，比肉眼扫go.sum更可靠 - 检查是否有
replace或exclude影响了模块解析逻辑 - 临时删掉
go.work（如果存在），避免工作区干扰单模块 tidy 行为
go mod tidy 后 vendor 目录没更新
默认情况下 go mod tidy 不碰 vendor/，它只同步 go.mod 和 go.sum。要让 vendor/ 跟上变化，得加 -v 参数。
使用场景：CI 构建要求离线编译，或团队强制走 vendor 流程。这时候漏掉 -v 就会导致本地能跑、CI 报 cannot find package。
立即学习“go语言免费学习笔记（深入）”；
- 执行
go mod tidy -v才会重新填充vendor/ -
go mod vendor是等价命令，但tidy -v更安全——它先 tidy 再 vendor，避免 vendor 过时依赖 - 注意
vendor/不会自动清理已删除模块的文件，得手动rm -rf vendor/ && go mod tidy -v
go mod tidy 慢或卡住的几个原因
本质是它在拉取 module proxy 元数据、校验 checksum、甚至回退到 vcs fetch，网络或配置不对就会卡住。
性能影响明显的情况：模块多、proxy 不稳定、本地 GOPROXY 设置为 direct、或模块用了私有域名但没配 GOPRIVATE。
- 优先设
GOPROXY=https://proxy.golang.org,direct，国内可换https://goproxy.cn - 私有模块必须加
GOPRIVATE=git.example.com/*，否则会尝试走 public proxy 导致超时 - 临时提速：加
-x看卡在哪一步，常是某个模块的go list -m -json请求 hang 住
go mod tidy 在 CI 中失败的典型错误信息
最常遇到的是 verifying github.com/xxx@v1.2.3: checksum mismatch，或 invalid version: unknown revision。这不是 tidy 本身的问题，而是 go.sum 和远程模块状态不一致。
根本原因是：有人手动改过 go.mod、或用 go get 覆盖了版本但没跑 tidy，又或者模块作者删了 tag。
- 修复方法：删掉
go.sum，再跑go mod tidy（谨慎！确保go.mod正确） - 更稳妥做法：
go mod download先拉全依赖，再go mod verify确认一致性 - CI 中建议加
go mod graph | wc -l做简单依赖规模检查，突增可能意味着意外引入
真正难处理的是跨 major 版本的隐式升级——比如 github.com/some/lib 从 v1 切到 v2，但没按规范用 /v2 路径，tidy 可能悄无声息换掉行为，这种得靠测试覆盖兜底。