Go go test -race 出错时怎么排查竞态报告

运行 go test -race 后，真正需要先判断的不是“退出码是不是 1”，而是输出属于哪一类：出现 WARNING: DATA RACE 就按竞态报告排查；只有 --- FAIL 而没有竞态段落，通常是普通测试断言失败；如果直接提示当前平台不支持 -race，则要先换到支持的平台。最稳妥的复查命令是 go test -race -count=1 ./path/to/pkg，先缩小范围，再回到完整包集合。

竞态报告不是告诉你“哪个 goroutine 先错了”，而是指出同一共享内存的冲突访问。重点看 Read by、Previous write，以及两条访问分别由哪里创建。

本文要记住的三点：先稳定复现；再把报告中的两条栈映射到同一共享对象；最后让读写都经过一致的同步边界。

先让报告稳定复现：不要先盯着退出码

-race 是运行时检测器，只有测试路径真的执行到冲突访问时才会报告。因此第一次排查不要直接跑整个仓库并猜测，先执行下面的命令：

go test -race -count=1 -run '^TestCounter$' ./internal/counter
# -race 打开竞态检测；-count=1 强制本次重新运行；-run 只保留目标测试
# 先缩小包和测试范围，便于把报告栈映射回当前改动

若输出是 WARNING: DATA RACE，继续读报告。若只有测试断言失败，先处理测试逻辑；若出现 race detector is not supported 一类提示，则不是代码竞态，先核对 go help testflag 和当前操作系统、架构组合。不要把检测器的非零退出当成唯一线索。

读竞态报告要抓住两条冲突访问

一份报告通常有四个有用位置：Read by goroutine N 指向一次读取，Previous write by goroutine M 指向冲突写入，后面的 Goroutine N created at 和 Goroutine M created at 则帮助你找到并发入口。先忽略运行时内部栈，从第一个属于自己项目的文件名和行号开始回看。

排查时可以在纸上写成三列：共享对象是什么、读写分别落在哪个函数、它们之间有什么同步关系。如果两次访问都触及同一个 map、slice、字段或指针，而中间只有“我认为 goroutine 已经结束”这样的推断，就应继续找显式的锁、channel、原子操作或等待关系。下面的框图只表达这些静态关系，不代表某次真实运行结果。

用最小改动消除共享写入

修复原则不是给报错行随手加锁，而是让同一共享状态的所有相关读写采用一致策略。下面的例子用互斥锁保护计数器；锁只属于这个状态，修改和读取都在短临界区内完成：

package counter

import "sync"

type Counter struct {
	mu sync.Mutex // 保护 value，所有读写都要经过这把锁
	value int
}

func (c *Counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock() // 无论函数如何返回，都释放锁
	c.value += delta
}

func (c *Counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock() // 读取也要与写入使用同一同步边界
	return c.value
}

如果状态适合单向消息传递，可以让一个 goroutine 独占它；如果只是简单整数，也可以评估原子操作。不要混用“写入加锁、读取裸奔”，也不要复制包含锁的结构体。修复后先重复目标测试，再运行包级命令；报告消失只是一个信号，还要确认原有断言没有被修改掩盖。

复查覆盖率、构建环境和报告选项

竞态检测依赖运行路径。单元测试没触发问题，不等于生产路径没有问题，可以增加并发场景、重复运行目标测试，或对用 -race 构建的程序施加接近真实的工作负载。为了减少报告噪声，可把输出写入文件：

GORACE='log_path=/tmp/go-race/report strip_path_prefix=/workspace/project' \
go test -race -count=1 ./...
# log_path 保存每个进程的报告；strip_path_prefix 只缩短显示路径

报告过长时可考虑 halt_on_error=1 先收集第一处冲突；看到 failed to restore the stack，再谨慎提高 history_size，因为它会增加内存开销。跨平台排查时，还要记录操作系统、架构和 Go 工具链；-race 并非所有平台都支持。

常见追问

为什么反复运行有时没有报告？

报告依赖运行时调度和测试覆盖，冲突路径没有被执行就不会出现。增加并发压力或扩大真实场景覆盖，比简单重复复制错误文本更有效。

退出码 66 是不是业务代码返回的？

不是。竞态检测器默认在发现竞态后使用自己的退出状态；可以通过 GORACE 的 exitcode 调整，但修复时应以报告中的冲突访问为准，而不是围绕数字做条件判断。

结论：把 go test -race 的错误拆成“能否运行、是否发现竞态、报告指向哪里、修复后是否复现”四个问题，排查会比盯着最后一行失败摘要更快。