Go test -race 如何只运行目标包的竞态检查

如果只想检查一个 Go 包，命令的核心不是给 -race 换一种写法，而是把包路径写窄。最小用法是 go test -race .；从模块根目录检查指定目录，则使用 go test -race ./internal/cache。不要写成 ./...，因为它会展开当前模块下的多个包。

官方资料：https://pkg.go.dev/cmd/go

先把目标包写成明确的包路径

我排查并发问题时，第一步会先确认当前工作目录。若当前目录本身就是目标包，使用点号即可；若站在模块根目录，就写目标包的相对路径。两种写法都只对应一个明确的包模式：

# 当前目录就是目标包；点号不会递归进入子目录
# 这条命令只对当前目录对应的一个包启用竞态检测
go test -race .

# 从模块根目录只检查 internal/cache 包
# 目标路径写得越明确，失败日志越容易归因
go test -race ./internal/cache

# 只检查显式列出的两个包；不要用 ./... 代替它们
go test -race ./internal/cache ./internal/queue

这里的 go test 是包选择器，-race 是构建和测试时的竞态检测开关，./internal/cache 才是“只运行目标包”的边界。一个常见误区是看到测试命令成功，就把“测试通过”理解成整个模块没有竞态；实际上它只说明本次列出的包完成了这轮测试。

区分包选择与测试函数筛选

如果目标包里测试很多，可以再加 -run，但它解决的是第二层问题：只运行名称匹配的测试函数。例如：

# 只在目标包中运行名称包含 Cache 的测试函数
# -run 不会改变目标包，也不会自动选择子包
go test -race -run 'Cache' ./internal/cache

因此，下面三条命令的含义完全不同：

我通常先用单包命令确认现象，再决定是否扩大到模块级。这样日志更短，失败也更容易归因；但单包通过不能替代全量门禁。

目标包与依赖包的边界要看清

“只运行目标包”不等于“只编译目标包的源码”。目标包的测试二进制仍然要解析和编译它依赖的包，这些依赖是构建图的一部分；真正执行哪些函数，则由测试代码和调用路径决定。竞态检测器也不是静态扫描器，它需要在运行过程中观察并发访问。

可以把一次单包检查理解为：目标包提供测试入口，*_test.go参与生成测试二进制，目标包再调用依赖包；竞态检测器只会对这次运行中被触达的共享访问留下报告。代码里存在一个没有被测试覆盖的 goroutine，并不会因为命令带了 -race 就自动暴露。

为本地排查和 CI 选择不同命令

本地定位时，我会先保留单包范围，并按需加测试筛选：

# 关闭成功结果缓存，避免重复排查时误看旧结果
# -count=1 只影响本次测试执行，不会扩大包范围
go test -race -count=1 -run 'TestCache' ./internal/cache

CI 门禁则可以把包路径写进脚本，让范围变更显式可审查。若要检查模块内全部包，才使用 ./...；若只关心几个高并发包，就列出它们。竞态检测通常会增加编译和运行成本，不能只把它无条件塞进每一次快速反馈。

还要留意平台边界和测试行为：官方文档列出了 -race 支持的平台；测试必须真正启动并发场景，检测器才有机会观察冲突。遇到超时，可以给单包命令加 -timeout，但不要用缩短超时来替代定位。

什么时候不该把单包结果当成最终结论

如果共享状态位于另一个包，而目标包的测试没有走到相关调用路径，单包检查只能说明当前路径没有报告。反过来，依赖包虽然不是命令行列出的目标，但它参与了目标包测试二进制的构建和运行，所以不要把“未列出依赖包”理解成“依赖包完全没有参与”。

我的取舍是：开发阶段用精确包路径缩短反馈，提交前对关键并发包使用 -count=1 做一次新鲜检查，CI 再按项目风险决定是否运行 ./...。命令越窄，归因越清楚；结论越全面，成本也越高。

常见问题速答

只运行当前包应该写什么？在目标包目录执行 go test -race .；从模块根目录则写该包的相对路径。

-run 能不能只检查一个包？不能。它只匹配测试函数、示例或基准名称，包仍由最后的包模式决定。

为什么单包通过，模块级 ./... 仍可能失败？其他包拥有不同测试路径或共享状态，单包命令没有覆盖它们。

每次都要加 -count=1 吗？不必。只有希望明确绕过成功测试缓存、重复观察当前代码状态时再加。