Go mod tidy 怎样避免误删测试依赖

我在整理一个 Go 模块时遇到过一个很容易误判的变化：业务包没改，go mod tidy 却调整了测试库和间接依赖。这个现象通常不是 tidy “误删”了测试依赖，而是整理范围、构建标签和当前测试入口没有对齐。

结论很简单：不要先手工把依赖加回去。先确认测试文件确实导入了它、条件测试的构建标签能被 tidy 看到，再用 go mod tidy -diff 预览差异，最后按项目的测试入口回归。官方参考：https://go.dev/ref/mod。

先分清 tidy 扫描的依赖范围

go mod tidy 的目标是让 go.mod 与模块源码保持一致。它会加载主模块中的包、工具及其递归导入，也会考虑测试导入；与只执行一次当前平台的 go test ./... 相比，扫描面更宽。构建标签默认按启用状态评估，ignore 标签是例外。

因此，测试专用模块出现在主模块的 require 中并不反常。只要它提供了某个测试或工具需要的包，它就有存在理由；反过来，如果测试文件已经移走、构建标签不再成立，tidy 也可能把原来的记录删掉。图1把这几个静态边界放在一起，便于先判断“依赖从哪里来”。

检查测试文件与构建标签

先找依赖的实际使用点，而不是只盯着 go.mod 的一行 require。重点看三类文件：普通的 _test.go、带 //go:build 的条件测试，以及项目里声明的测试或开发工具。某个依赖只在特定标签下被导入时，日常测试未必能暴露它的缺失。

构建约束必须放在文件顶部、包声明之前，并和项目约定的标签一致。标签名写错、只保留旧式约束、或者把测试放在不会被模块加载的目录，都可能让“我明明写了测试依赖”的判断失真。整理前先把测试依赖按用途分组：单元测试库、集成测试工具、代码生成工具，不要混成一张长期手工维护的清单。

//go:build integration

package storage_test

import (
    "testing"

    "example.com/project/testkit"
)

func TestStorageIntegration(t *testing.T) {
    // 只有带 integration 标签的测试才需要这组集成测试依赖。
    testkit.RequireService(t, "storage")
}

这段代码只说明依赖的静态归属，不代表本轮已经执行集成测试。真正要确认的是：团队的测试命令是否会传入相同标签，以及 CI 是否拥有它需要的外部服务。

用 go mod tidy -diff 预览变更

直接运行 tidy 会改写 go.mod 和 go.sum。在提交前，先使用 -diff 只查看统一差异，确认变化是否符合刚才的依赖归属判断：

# 只预览模块文件差异，不直接写回 go.mod 和 go.sum。
go mod tidy -diff

# 用项目约定的条件运行测试；标签名称要与测试文件保持一致。
go test -tags=integration ./...

# 确认差异经过审阅后，再正式整理模块记录。
go mod tidy

-diff 不是“只整理测试依赖”的开关，它只是把本来会产生的模块文件变化打印出来。看到某个测试库被移除时，回到导入点和构建标签；看到新的间接依赖时，确认是不是测试或工具的递归依赖。不要只因为 diff 变小就认定结果正确。

按测试入口回归依赖

整理后的回归至少要覆盖项目实际支持的测试组合，而不是只跑开发者本机默认路径。没有条件标签的单元测试先跑一遍；有集成标签、平台标签或工具生成步骤的项目，再按 CI 的命令复现。重点观察三种结果：

如果项目使用多模块或工作区，还要确认当前命令是在正确的模块根目录执行。go.work 会影响工作区中的主模块集合，但不会把任意目录下的测试自动变成当前模块的一部分。依赖缺失时，先确认工作目录、模块边界和测试入口，再决定是否修正 go.mod。

把整理边界放进发布检查

我更愿意把 tidy 当作一次可审阅的变更，而不是提交前的“顺手清理”。发布检查可以固定四项：记录执行目录；保存 go mod tidy -diff 的审阅结果；按默认与条件测试入口回归；最后确认 go.mod、go.sum 和构建标签文件一起提交。

不要采用两种极端做法：一是为了让 diff 消失，手工把测试依赖写回去；二是把所有测试库都塞进永久直接依赖。前者会掩盖真实导入边界，后者会让模块记录失去“当前源码需要什么”的信息。更稳妥的做法是修正测试文件、标签或命令，再让 tidy 根据源码重新计算。

为什么我本机测试通过，CI 却提示测试依赖缺失？

最常见的原因是 CI 使用了额外的构建标签、不同平台文件或不同模块目录。本机默认测试只覆盖了较窄的依赖集合，不能替代 CI 的完整入口。

测试专用库一定要写成 indirect 吗？

不要按用途直接决定。是否出现 // indirect 取决于它是否被主模块中的包直接导入，以及 Go 的模块图规则；应以源码导入和 tidy 结果为准。

可以只删除 go.sum 里的测试依赖校验吗？

不建议手工按关键词删。go.sum 记录的是模块校验信息，应该随模块图和依赖导入一起由 Go 工具整理；先找出依赖来源，再审阅 tidy 的差异更安全。