WaitGroup 计数为什么会变成负数，Add 与启动协程的顺序如何安排

我在排查一段批量任务代码时，先看到的是熟悉的 sync: negative WaitGroup counter，随后又发现另一处代码没有 panic，却在任务还没开始时就结束了等待。两种现象都和 WaitGroup 有关，但修法并不相同：前者是“注销次数超过登记次数”，后者是“Wait 看到计数仍为零”。

官方文档：https://pkg.go.dev/sync

把计数器看成任务合同：Add 先于 go

WaitGroup 不是“帮我启动协程”的容器，它维护的是待完成任务数。Add(1) 表示签下一份任务合同，Done() 表示合同完成，Wait() 只关心计数是否回到零。因此登记动作必须在创建任务前完成：

var wg sync.WaitGroup

for _, item := range items {
	// 先登记任务，避免 Wait 观察到仍为零的计数。
	wg.Add(1)
	go func(item Item) {
		// 无论中途 return 还是处理失败，都要注销这次登记。
		defer wg.Done()
		process(item)
	}(item)
}

// 所有登记动作已经完成，再等待任务计数归零。
wg.Wait()

这里的关键不是“Add 必须在同一行”，而是正向增加计数的时机：当计数器原本为零时，Add(1) 要先于 Wait。如果把它放到 goroutine 内，主 goroutine 可能先执行 Wait，看到零后直接继续，新的任务才刚开始登记。

为什么计数会变成负数：先找多出来的 Done

官方定义很直接：Done() 等价于 Add(-1)，计数器一旦小于零就 panic。最常见的排查顺序是把每个登记点和注销点配对，而不是先给 WaitGroup 加锁：

一个容易忽视的坑是“主流程已经 defer Done，错误分支又手写一次 Done”。这种写法看起来是在补偿异常路径，实际会让同一个任务减两次。把 defer wg.Done() 放在 goroutine 函数的第一段通常更稳，然后只让业务代码负责返回错误。

负数、早退与复用是三种不同故障

不要把所有 WaitGroup 问题都归因于调度器。负数 panic 是计数账本已经被扣穿；Wait 早退是登记和等待发生在同一个零计数窗口；批次复用则是上一组任务尚未完全退出，就开始登记下一组。

如果要连续处理多批任务，可以把每一批封装成一个函数，让这一批的 Add、启动和 Wait 在同一层完成：

func runBatch(items []Item) {
	var wg sync.WaitGroup
	for _, item := range items {
		// 当前批次先完成登记，再创建对应任务。
		wg.Add(1)
		go func(item Item) {
			defer wg.Done() // 统一覆盖正常返回和错误返回。
			process(item)
		}(item)
	}
	// 返回前收口当前批次，下一批不会抢用这个计数器。
	wg.Wait()
}

官方文档还提醒，WaitGroup 在第一次使用后不能复制。项目基线如果已经支持 Go 1.25+，WaitGroup.Go 可以把 Add、启动 goroutine 和返回时的 Done 收到一个方法里；但它不替代任务边界设计，传入的函数也不能 panic。旧版本项目继续使用 Add/Done 没有问题。

把这份检查清单放进代码评审

• 每个 Add(+1) 是否明确对应一个任务，而不是对应一次循环重试？
• Done 是否在 goroutine 入口立即 defer，是否存在第二个注销点？
• 是否可能在计数器为零时并发执行正向 Add 与 Wait？
• 复用 WaitGroup 前，上一轮 Wait 是否已经返回？结构体是否意外复制过？

相关问题

把 Add 放在 goroutine 里一定会 panic 吗？

不一定。它更直接的风险是 Wait 可能提前返回；当计数仍大于零时再增加任务也可能符合规则，但初始登记必须先完成，代码更容易读和审查。

为什么推荐 defer wg.Done？

它把注销动作绑定到 goroutine 返回，不容易遗漏错误分支；前提是每个任务只登记一次，不能再额外手写 Done。

WaitGroup 能不能跨批次复用？

可以，但下一批的 Add 必须等上一批 Wait 返回后再开始；如果批次关系复杂，分批创建局部 WaitGroup 通常更清楚。