Go mod tidy 删除依赖后构建失败怎么办

Go mod tidy 删除依赖后构建失败，通常不是 tidy 随机误删，而是 tidy 看到的“主模块源码集合”和实际构建输入不一致。它会根据当前模块的包、工具和测试导入关系维护 go.mod；没有为这些包提供内容的模块就可能被移除。先保留差异，再找出构建命令真正导入的包，通常比直接把整行 require 加回去更稳妥。

官方文档：https://go.dev/ref/mod

先把被删除的依赖和构建上下文固定下来

在干净工作区先保存差异。-diff 只打印将要修改的 go.mod 和 go.sum，不会直接写回；正式执行前还可以用 -v 看被移除的模块。

# 先保存 tidy 预览，避免把原始依赖变化混在其他改动里
go mod tidy -diff > /tmp/tidy.diff

# 记录当前模块根目录、工作区和全局构建选项
go env GOMOD GOWORK GOFLAGS

# 查看依赖文件中与本次问题有关的变化
git diff -- go.mod go.sum vendor/modules.txt

如果项目有 go.work，先确认命令是在预期的主模块目录运行；如果存在 vendor，还要确认它是否由当前的 go.mod 重新生成。不要把旧的 vendor/modules.txt 当成 tidy 结果，它可能只是上一轮依赖图的快照。

沿着实际导入路径判断“为什么它不在依赖图里”

最有价值的证据是构建失败的包路径和源码中的 import。用 go list 查看当前模块能加载的依赖，再用 go mod why -m 解释某个模块是否有从主模块出发的导入路径：

# 列出当前模块包及其依赖，PACKAGE_OR_PATTERN 替换为实际包
go list -deps ./...
go list -deps ./path/to/package

# 查看模块是否仍能从主模块的导入图抵达
go mod why -m example.com/needed/module

# 检查构建使用的模块版本和 replace 关系
go list -m all
go mod edit -json

有几类情况容易造成错觉：依赖只出现在生成文件里，而生成动作发生在 tidy 之后；依赖被 go:generate 当作命令调用，却没有 Go import；项目实际构建的是另一个子模块；或者代码通过插件、反射、脚本按字符串加载包。它们都不能单靠一行手工 require 解决，必须先让构建输入和模块边界表达真实关系。

按根因修复，不要用重复 tidy 对抗结果

如果缺少的包确实在源码中被导入，先修正模块根目录、生成文件提交时机或错误的 import 路径，再运行 go get example.com/needed/module/path 让 Go 重新解析提供该包的模块，最后执行 tidy。若它只是生成工具，应把工具放进单独的工具模块或显式的工具依赖管理中；若它是运行时通过配置或插件加载，则要在发布构建的输入里保留对应模块，并把这条约束写进 CI。

不要为了“看起来稳定”给每个模块都加 // indirect。indirect 只描述当前主模块没有直接导入该模块的状态，不能替代真实的源码导入。-e 也只是让 tidy 遇到加载错误时尽量继续，它不会把不可见的运行时依赖变成可推导依赖。

把 vendor、workspace 和 CI 的路径对齐

Go 官方说明中，go mod tidy 会加载主模块的包、工具、递归导入和测试，并按除 ignore 外的 build tags 处理；它并不等价于“把所有可能被程序动态使用的库列出来”。如果 CI 用 -mod=vendor、特定 -tags 或另一个子模块构建，就应让 CI 先执行与本地相同的准备动作：

# 依赖文件稳定后再生成 vendor，避免使用过期清单
go mod tidy
go mod vendor

# 使用仓库实际的构建入口复查；按项目约定替换 ./...
go test ./...
go build ./...

# 发布前确认 tidy 不再产生差异
go mod tidy -diff

若团队要求保留未被源码导入的工具依赖，不要把它混进应用模块的“自动推导结果”里。可以使用单独的 tools.go 约定或独立 tools module，但要让安装命令、生成命令和 CI 明确指向同一个模块根目录。

用一轮反向检查确认问题真的结束

修复不以“手工加回依赖”作为完成标志，而以可重复为准：在同一模块根目录执行 go mod tidy 后工作区没有意外变化；go test ./... 和正式构建入口都能找到缺失包；如果使用 vendor，vendor/modules.txt 与 go.mod 同步；CI 与本地的 GOWORK、-mod、-tags 约束一致。这样下一次 tidy 仍然会得到同样的依赖图。

相关问题

go mod tidy 会删除测试依赖吗？

它会加载主模块包及测试导入，因此真正被测试源码导入的依赖通常会保留；如果测试在另一个模块、生成后才出现，或根本没有 Go import，就要检查测试入口和模块边界。

加上 indirect 能永久解决构建失败吗？

不能。它只能暂时改变 go.mod 文本，不能表达动态加载、生成代码或错误模块根目录造成的依赖关系，下一次 tidy 仍可能删除。

tidy 后 vendor 报不一致怎么办？

先确认在正确的主模块根目录完成 tidy，再重新运行 go mod vendor，并把生成后的 vendor 变化作为同一次依赖变更提交。