go mod tidy 为什么会加入看似未使用的模块

项目明明没有在当前业务代码里直接导入某个包，运行 go mod tidy 后，go.mod 却多出一条 require，甚至还带着 // indirect。这通常不是 tidy 乱加依赖，而是它扫描的范围比一次普通构建更完整：会考虑主模块的代码、测试、工具包、构建标签以及不同平台文件。先找到“谁需要这个模块”，再判断它是否应当保留，才是正确处理方式。

先分清 tidy 正在整理哪一组依赖

go mod tidy 的目标是让 go.mod 与模块源码保持一致。它会加载主模块中的包、这些包递归导入的依赖、工具依赖和测试依赖；测试还可能来自被依赖模块。与此同时，tidy 会把构建标签视为可启用的条件，检查不同操作系统或架构可能被编译到的文件。

所以，下面这段代码在 Linux 主程序中没有出现，并不代表它对 tidy 不存在：

package storage

import (
    // 这个导入只在当前平台对应的文件中使用。
    "example.com/platform/driver"
)

var _ = driver.Open

如果它位于 storage_windows.go、tools.go 或测试文件中，当前机器执行的 go build ./... 可能不加载它，但 tidy 仍会把它视为模块内容的一部分。新增的模块因此可能是“其他构建条件下的直接依赖”，而不是普通代码里的无效行。

用依赖路径确认模块为什么被加入

不要看到 // indirect 就直接删除。这个标记描述的是“主模块没有直接导入该模块的包”，不等于它没有作用。先运行下面的命令，把模块名替换成新增的路径：

# 先看某个模块能否从主模块的包或测试中追溯到
go mod why -m example.com/platform/driver

# 列出当前条件下的包依赖，便于和 tidy 结果对照
go list -deps ./...

# 查看模块要求形成的边，包含 replace 处理后的关系
go mod graph

go mod why -m 能帮助确认入口；如果当前条件下没有路径，不代表结论已经完成，因为平台文件和测试可能没有被本次 go list 选中。此时应继续搜索仓库中的 import、go:build、tools.go 和测试文件，再把依赖路径分成四类：

go 指令版本为什么也会改变结果

主模块的 go 指令会影响模块图处理方式。Go 1.17 及以上支持模块图裁剪和惰性加载，go.mod 往往会保留更明确的间接要求，使构建所需的版本集合可复现。执行带版本参数的 tidy，还可能因为模块图规则变化而增删间接依赖：

# 只查看变化，不立即改写 go.mod 和 go.sum
go mod tidy -diff

# 明确按目标 Go 版本整理，并检查旧版本兼容性
go mod tidy -go=1.22 -compat=1.21

这里的 -go 不是“选择编译器版本”的快捷开关，而是修改模块声明并按照对应规则整理依赖；如果项目本身并不准备升级模块版本，不要为了消除一条间接依赖随意传入它。

一套可回滚的处理流程

实际排查时，我会先保存当前改动，然后执行 go mod tidy -diff。确认差异后，针对新增模块运行 go mod why -m，再检查未被当前平台选中的源码、测试和工具入口。若模块确实服务于测试或生成流程，就保留它并在团队文档中说明用途；若是废弃文件、错误的 build tag 或过时工具引用，则修复入口后再次整理。

最后再执行目标测试与构建，而不是手工删除 go.mod 的一行。一个新增模块只有在所有相关入口都移除、并且 go mod tidy -diff 不再提出变化时，才算真正清理完成。

常见问题

为什么 go build 通过，go mod tidy 还会改 go.mod？

build 受当前平台、标签和目标包限制；tidy 会覆盖测试、工具和更多构建条件，因此两者扫描集合不同。

间接依赖能不能直接删掉？

不建议。先找出测试、工具或平台文件中的入口；没有入口且 go mod tidy -diff 能稳定移除时，才说明删除是结果而不是猜测。

go.sum 也变了是不是下载了无用模块？

不一定。go.sum 记录模块内容校验信息，tidy 可能为测试、跨平台或兼容版本保留校验项。应结合依赖路径和目标 Go 版本判断。