根本原因是Go模块的“最小版本选择”（MVS）机制：只要间接依赖被任一直接依赖声明在go.mod中，go mod tidy就会将其拉入顶层go.mod，即使代码未import。
为什么 go mod tidy 会拉入不该有的依赖
根本原因是 Go 模块的“最小版本选择”（MVS）机制：只要某个间接依赖被任意一个直接依赖声明在它的 go.mod 里，go mod tidy 就会把它拉进你的项目顶层 go.mod，哪怕你代码里一行都没 import 它。这不是 bug，是设计使然——但对依赖收敛很不友好。
常见诱因包括：
- 你依赖的库 A 依赖了库 B（比如
github.com/some/a→github.com/some/b），而 B 又悄悄引入了golang.org/x/tools这类重型工具包 - 某个测试用的
require被错误写进了生产模块的go.mod - 本地
replace或exclude没生效，因为go mod tidy会自动清理未被引用的exclude条目
用 go mod edit -dropreplace 和 -dropexclude 清理残留
go mod edit 是唯一能安全修改 go.mod 结构而不触发自动重写的方式。尤其当你要删除 replace 或 exclude 后再重新验证时，必须先清掉旧条目，否则 tidy 可能忽略你的意图。
实操步骤：
- 删掉所有 replace：
go mod edit -dropreplace=github.com/old/lib
- 删掉某条 exclude：
go mod edit -dropexclude='github.com/bad/dep v1.2.3'
- 批量清空 exclude（谨慎！）：
go mod edit -dropexclude=all
- 执行后务必手动运行
go mod tidy -v观察输出，确认没意外拉入新依赖
用 //go:build ignore 隔离测试/工具依赖
很多隐式依赖来自 _test.go 文件或构建标签启用的工具代码（比如生成器、linter 配置）。Go 不会为 test 或 tools 构建目标解析依赖，但 go mod tidy 默认扫描全部文件。
正确做法是把纯工具代码放进独立目录，并加构建约束：
package tools import _ "golang.org/x/tools/cmd/stringer" import _ "github.com/golangci/golangci-lint/cmd/golangci-lint"
然后在该文件顶部加：
//go:build tools // +build tools package tools
再在主 go.mod 中显式 require 工具模块（防止 CI 环境缺失）：
go mod edit -require github.com/golangci/golangci-lint/cmd/golangci-lint@v1.54.2
这样 go mod tidy 就不会把它当作运行时依赖处理。
CI 中用 go list -m all 做依赖白名单校验
禁止隐式依赖最可靠的方式不是靠人盯，而是让 CI 拒绝任何未明确定义的模块出现在最终依赖图中。
在 CI 脚本中加入：
#!/bin/sh
set -e
ALLOWED_DEPS="\
github.com/sirupsen/logrus \
go.uber.org/zap \
golang.org/x/net \
"
for mod in $(go list -m -f '{{.Path}}' all); do
if ! echo "$ALLOWED_DEPS" | grep -q "^$mod\$"; then
echo "ERROR: unexpected module $mod" >&2
exit 1
fi
done
注意点：
-
go list -m all输出的是 MVS 下实际解析出的所有模块，比go.mod更真实 - 白名单要包含所有直接依赖 + 显式需要的间接依赖（比如你用了
grpc-go的某个子包，它依赖golang.org/x/net/http2，那后者也得进白名单） - 别忘了排除
std和cmd等标准库模块，它们不会出现在go list -m all输出里
真正难控的从来不是怎么写规则，而是谁来维护那份白名单——每次加一个新库，都得同步更新它，否则 CI 立刻失败。这恰恰是约束生效的前提。
