Go race 检测到测试数据竞争但单线程运行正常为什么

会出现这种情况，通常不是 go test 和 go test -race 谁“测错了”，而是两次运行走过的调度和访问时序不同。普通测试输出正常，只能说明这一次没有把冲突暴露出来；如果多个 goroutine 访问同一个变量且至少有一次写入，仍然可能存在数据竞争。

先把问题缩成共享状态的最小复现，再用 go test -race 重复触发。修复时要让同一共享变量的所有读写经过同一个同步边界，不能只锁写入或只依赖“现在看起来是单线程”。

为什么普通测试正常，-race 却能发现问题

普通测试往往只启动一个 goroutine，或者测试数据很小，主 goroutine 在后台任务真正执行前就完成了读取。加入 -race 后，程序会插入竞态检测指令，执行速度、调度时机和内存访问交错都可能变化，于是原本“碰巧排队”的读写出现重叠。

这里要区分两个结果：测试失败表示业务断言没有满足；竞态报告表示访问关系本身不安全，即使最终数值仍然正确也要处理。官方文档对 data race 的定义是：并发访问同一变量，且至少一个访问是写入。

先用共享计数器做最小复现

把网络、日志和业务对象都拿掉，只留下一个被多个 goroutine 更新的整数，最容易判断报告是否对应真实问题：

func TestCounter(t *testing.T) {
	var n int
	var wg sync.WaitGroup
	for i := 0; i 

将文件保存为 counter_test.go 后运行：

go test -race -run TestCounter
# -race 让测试运行时检查并发读写
# -run 只执行这个最小用例，便于缩短排查范围

报告里的 Read、Write 栈通常会分别指向 n++，后面的 goroutine 创建栈则帮助你确认它们来自哪条并发路径。不要只盯着最后一行测试失败信息。

沿数据生命周期检查真正缺少的同步

定位到变量后，按“创建—传递—读取—修改—结束”检查它的所有路径。常见误判有三种：

WaitGroup 适合等待任务完成，不负责保护任务运行期间的数据。若状态只是一个整数计数器，可用 atomic.Int64；若多个字段必须一起保持一致，则把相关读写放进同一把 sync.Mutex 的临界区。通道则适合把数据所有权从生产者转交给消费者，减少共享可变状态。

修复后要让所有读写经过同一边界

原子计数的写法如下，关键不是“加一个原子函数”，而是不要再混用普通读写：

var n atomic.Int64

for i := 0; i 

如果更新动作还要同时改变状态、时间戳和错误标记，就不要硬拆成多个原子变量；用互斥锁把这一组不变量包起来通常更清楚。修复后再次运行 go test -race ./...，并增加能覆盖高并发、重复调用和取消路径的测试。竞态检测是运行时工具，没执行到的分支不会自动被证明安全；官方文档也建议在真实负载下运行带 -race 的程序来扩大覆盖。

常见问题

看到 race 报告就一定会出现错误结果吗？

不一定。它说明访问关系没有被同步约束，当前结果可能只是碰巧正确；未来调度或负载变化仍可能产生错误。

为什么本地运行没报告，CI 却报告？

两边的 CPU、测试顺序、并发量和执行时间不同。优先保留 CI 能触发的场景，缩小到最小测试后修复，不要通过降低并发来掩盖问题。

只运行一次 go test -race 没报告，可以合并吗？

不能据此下结论。它只覆盖本次执行路径，应补充重复运行、压力数据和关键异常分支，再结合代码中的同步边界判断。

参考：Go Data Race Detector 官方说明。