go test race与超时一起使用怎么排查

可以同时使用，但排查时不要把两个信号混成一个结论：先运行普通测试建立基线，再运行 -race，最后根据超时堆栈、测试截止时间和 race 报告判断原因。一个常用起点是 go test -race -timeout=2m ./...，但 2 分钟只是测试二进制的时间边界，不代表每个测试都应该在 2 分钟内完成。

如果普通模式通过、race 模式超时，优先怀疑检测开销放大了慢测试，或 race 模式触发了更完整的并发路径；如果两种模式都超时，再把重点放到 goroutine 没有退出、等待条件永远不满足或外部依赖没有截止时间。

先分开基线测试与 race 测试

第一轮不要直接反复加大超时时间。先用同一组包分别跑普通测试和 race 测试，比较“是否失败、失败在哪个测试、耗时是否明显增加”。

# 先关闭测试缓存，得到一次真实的普通模式基线
go test -count=1 -timeout=30s ./path/to/pkg

# 只对同一包开启竞态检测，避免 ./... 的噪声掩盖问题
go test -count=1 -race -timeout=2m ./path/to/pkg

# 已经知道测试名时缩小范围，并保留详细日志
go test -count=1 -race -v -run 'TestCache|TestWorker' -timeout=90s ./path/to/pkg

-race 是运行时检测：只有被测试真正执行到的并发访问才有机会出现在报告中。它通常会增加 CPU、内存和运行时间，所以基线命令的通过并不能证明 race 命令也会在同一个时间预算内完成。下图把命令参数、测试二进制、race runtime 与 timeout 边界放在同一张静态关系图中，便于先判断信号属于哪一层。

看懂 -timeout 与测试截止时间

-timeout 控制测试二进制运行多久后触发 panic，默认值是 10 分钟，设为 0 才表示关闭该限制。它不是给每个 goroutine 自动注入取消信号，也不会替你关闭网络连接、定时器或后台 worker。

在测试内部可以读取测试框架的截止时间，把它转换成业务代码能够理解的 context。这样一旦 race 模式让剩余时间变短，子操作仍然有机会提前停止，而不是等整个测试进程被强制 panic。

func TestWorkerStopsBeforeDeadline(t *testing.T) {
	// 读取 -timeout 形成的测试截止时间，给业务操作留下收尾余量。
	deadline, ok := t.Deadline()
	if !ok {
		deadline = time.Now().Add(30 * time.Second)
	}
	ctx, cancel := context.WithDeadline(context.Background(), deadline.Add(-200*time.Millisecond))
	defer cancel() // 测试结束时释放计时器和关联资源。

	if err := runWorker(ctx); err != nil {
		// 取消通常是测试超时的线索，保留错误上下文便于定位阻塞点。
		if errors.Is(err, context.DeadlineExceeded) {
			t.Fatalf("worker exceeded test deadline: %v", err)
		}
		t.Fatal(err)
	}
}

排查时先看超时 panic 后的 goroutine 栈：如果大量 goroutine都卡在同一个 channel receive、WaitGroup 等待或外部 I/O，问题更像生命周期没有收口；如果只是在 race 模式下耗时成倍增长，则先调大 race 专用时间预算，同时保留普通模式的基线结果。

让 race 报告可定位

真正的 race 报告通常包含冲突读写栈，以及创建相关 goroutine 的栈。不要只看第一行 WARNING: DATA RACE，要把“哪一个共享变量、哪两个访问、由谁创建”串起来。需要长期保存报告时，可以让 race runtime 写到指定目录。

# 保存每次进程的 race 报告，并缩短项目路径
mkdir -p /tmp/go-race-report
GORACE="log_path=/tmp/go-race-report strip_path_prefix=$(pwd)" \
  go test -count=1 -race -v -timeout=2m ./path/to/pkg

# 只在需要复现某个并发测试时再次运行，避免报告被无关包淹没
GORACE="halt_on_error=1 exitcode=66" \
  go test -count=1 -race -run '^TestWorker$' ./path/to/pkg

halt_on_error=1 适合先锁定第一处竞争；它不是修复方案，修复后仍应回到完整相关测试。若 race 报告没有出现而测试超时，说明“已触发数据竞争”这个结论没有证据，继续检查阻塞栈和测试清理逻辑。

用最小回归命令收口

修复后按由窄到宽的顺序回归：先跑单个测试，再跑包级 race，最后才跑整个模块。每次都保留 -count=1，避免缓存让你误以为问题消失。

最小收口命令可以写成：

# 单测确认修复，再扩展到包和全模块
go test -count=1 -race -run '^TestWorker$' -timeout=90s ./path/to/pkg
go test -count=1 -race -timeout=2m ./path/to/pkg
go test -count=1 -race -timeout=5m ./...

关键是把“超时预算”和“竞态证据”分别记录。这样既不会因为 race 的正常开销误判死锁，也不会因为单纯加大 -timeout 而遗漏后台 goroutine 未退出的问题。

相关问题

为什么 go test -race 比普通测试慢很多？ 因为 race 模式会插桩并记录运行时内存访问，CPU、内存和耗时都会增加，具体幅度取决于程序和测试覆盖。

把 -timeout=0 加上就能解决卡死吗？ 不能。它只是关闭测试框架的总时间限制，真正的阻塞仍需通过 goroutine 栈、context 和资源清理定位。