Go mod why 怎样定位测试代码带入的依赖

如果你发现一个模块明明没有被业务代码直接导入，却出现在依赖清单里，先不要急着删除 go.mod 中的 require。测试文件、测试依赖的包，以及模块图中的间接路径，都可能让它成为当前主模块的可达依赖。定位这类问题最直接的入口是 go mod why：它会给出从主模块到目标包或目标模块的一条最短导入路径。

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

这篇只解决“测试代码把某个依赖带进来，究竟是谁引入的”这个问题，不讨论版本升级策略。最终可以得到三种结论：业务代码确实需要、测试代码需要，或者目标模块根本不在当前包图中。

• 查具体包：使用 go mod why 包路径。
• 查整个模块：使用 go mod why -m 模块路径。
• 排除依赖自身测试的影响：在支持的语义下加入 -vendor。

为什么测试依赖会出现在模块图里

Go 的模块命令不是只看生产源码。官方说明中，go mod why 默认查询由 go list all 匹配的包图，而这个集合会包含可达包的测试；go mod tidy 也会加载主模块包、工具及其递归导入，并考虑测试导入。因此，一个只写在 _test.go 中的导入，也可能解释某个模块为何出现在整理后的依赖关系里。

这里要先区分两件事：go mod why 解释“为什么需要它”，go mod graph 更适合解释“哪个模块声明了哪个版本”。前者解决来源，后者补足版本选择和依赖边。

用 go mod why 找到最短导入路径

先进入包含 go.mod 的模块目录，再指定一个你怀疑多余的包。下面的命令以包路径为例，输出中的每一行代表导入图上的一个节点：

# 查询目标包从主模块出发的最短导入路径
go mod why example.com/telemetry/trace

# 同时查询多个包，便于比较它们是否经过同一个测试入口
go mod why example.com/telemetry/trace example.com/telemetry/metric

结果通常以 # 目标包 开头，下面跟着从主模块、业务包或测试包到目标包的路径。如果输出类似“main module does not need package”，说明该包没有被当前查询范围引用；此时不要把“它写在 go.mod 里”误认为“它一定参与了当前包图”。

模块级排查用 -m，想隔离依赖测试再看 -vendor

当目标是一个模块而不是某个包时，使用 -m。它会把参数当作模块列表，并尝试找到该模块中任意包的路径，适合排查“这个模块为什么整体出现在构建依赖里”。

# 按模块查询，避免手动猜模块里的具体包路径
go mod why -m example.com/telemetry

# 只关注主模块需要的依赖视角，减少依赖自身测试带来的干扰
go mod why -vendor -m example.com/telemetry

-vendor 的含义不是“读取 vendor 目录”，而是让 why 排除依赖模块自身的测试导入。它更适合回答“如果不把依赖的测试算进来，主模块还需要它吗”。如果项目使用较新的 go 指令，官方文档还特别说明 all 的含义已经变化，所以不要只凭旧文章判断输出范围。

go mod why 说清“需要”，go mod graph 说清“谁声明”

如果 go mod why -m 只能告诉你模块可达，却没有解释版本为什么是当前值，再用模块图查看边：

# 输出模块之间的 require 关系，便于锁定声明者
go mod graph | grep 'example.com/telemetry'

# 查看最终选择的模块版本，避免只看 go.mod 的某一行
go list -m all | grep 'example.com/telemetry'

go mod graph 的每行可以看成“消费模块—被要求模块”的关系；go list -m all 则展示经过最小版本选择、替换和排除后最终采用的版本。也就是说，why 负责回答来源路径，graph 和 list -m all 负责补上版本关系。

定位后怎样判断要不要清理

看到路径后按来源做决定，不要直接手改 require：

修改源码或测试依赖后，再运行一次 go mod tidy，把整理动作交给 Go 命令完成；若只想预览变更，可使用 go mod tidy -diff，这样不会直接改写 go.mod 和 go.sum。

常见问题

为什么 go mod why 没有显示我想象中的依赖链？它展示的是一条最短路径，不是所有可能路径；需要完整声明关系时补看 go mod graph。

为什么加了 -m 之后结果变了？-m 把查询对象从包改成模块，并在模块内寻找任意可达包，结果自然可能与指定单个包不同。

为什么删掉 require 后又被 tidy 加回来？通常说明业务包、测试包或构建标签下的源码仍然让该模块可达，应先重新用 go mod why 找来源。

实际排查时可以记住一条顺序：先用 go mod why 找“谁把它带进来”，再用 -m 缩小到模块级，必要时用 -vendor 区分依赖测试，最后用 go mod graph 解释版本边。这样既不会把测试依赖误判成运行时依赖，也不会把版本选择问题误当成未使用模块。