go doc 依赖不会出现在 go.mod 中，因其仅读取源码注释而不导入包；所谓“文档依赖”实为示例文件（如 example_test.go）中的真实 import，go mod tidy 会保留它们，需通过 go mod why -test 识别并手动清理或挪至带构建标签的独立目录。
go doc 依赖不会出现在 go.mod 中
文档生成本身不引入运行时依赖，go doc、godoc（已弃用）或 pkg.go.dev 都只读源码注释，不 import 任何包。所谓“用于文档生成的代码”，其实是你写在注释里的示例代码（比如 // Example: fmt.Println("hello")），它只是字符串，不会触发模块加载，更不会被 go mod tidy 记录或清理。
真正会被误判为“文档依赖”的是测试/示例文件中的 import
容易混淆的是：你在 example_test.go 或 doc.go 里写了真实 import，比如：
package mypkg
import (
"fmt"
"testing"
)
func ExampleHello() {
fmt.Println("hello")
// Output: hello
}
这种情况下，fmt 是真实依赖，但仅在测试构建时生效。问题在于：go mod tidy 默认会扫描所有 .go 文件（包括 *_test.go），所以它会保留 fmt —— 这不是 bug，是预期行为。但如果你的示例文件里 import 了重型模块（比如 github.com/spf13/cobra 仅用于一个 ExampleCLI()），它就会被当成有效依赖留下。
- 确认方式：
go mod why -m github.com/spf13/cobra -test，若返回路径含example_test.go或doc.go，说明它只被测试/示例引用 - 安全移除条件：该模块未被任何非测试文件 import，且你不需要运行
go test时执行这些示例（即不依赖go test -run=Example） - 手动清理：删掉对应
import行，再跑go mod tidy -v，观察是否出现removing unused github.com/spf13/cobra
构建时彻底排除测试/示例依赖：用构建标签 + 分离目录
如果某些模块纯粹服务于文档示例，又不想污染主依赖图，最干净的做法是物理隔离：
- 把所有带 import 的示例代码移到
examples/子目录（而非*_test.go），并加//go:build example标签 - 主模块的
go.mod不会扫描examples/目录，除非你显式go build ./examples/... - 文档生成仍正常工作：
go doc不关心构建标签，只要注释存在就提取 - CI 构建时默认不包含
exampletag：GOOS=linux go build ./...不会拉取那些模块
别信 replace 或 exclude —— 它们不解决根本问题
replace 和 exclude 是针对模块冲突或临时绕过的，不是用来“隐藏文档依赖”的。例如：
exclude github.com/spf13/cobra v1.8.0
这会导致所有依赖它的路径编译失败（包括你自己的 example_test.go），而 go mod tidy 也不会帮你验证是否真能删——它只管语法层面的 import 引用。
真正要排除的从来不是“文档依赖”，而是你放进示例文件里的真实 import；识别它们靠 go mod why -test，清理靠删代码或挪目录。构建系统本身没有开关能一键过滤“文档用模块”，因为 Go 没有这种概念——只有你写的 import，和它实际参与的构建场景。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
