当前位置：首页 > 文章列表 > Golang > Go问答 > WaitGroup 计数为什么会变成负数，Add 与启动协程的顺序如何安排

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

来源：17golang原创 2026-10-07 09:34:30 0浏览收藏

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

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

要点速览

稳定写法是先 Add(1)，再执行 go，并在 goroutine 内用 defer wg.Done()。
计数变负只说明增减不匹配；Add 放进 goroutine 则可能让 Wait 提前返回，这是两个独立问题。
复用同一个 WaitGroup 时，上一轮 Wait 返回后再登记下一轮；支持 Go 1.25+ 时可评估 WaitGroup.Go。

把计数器看成任务合同：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，看到零后直接继续，新的任务才刚开始登记。

WaitGroup Add、任务计数、goroutine、Done 和 Wait 的静态关系说明图 — 图1：WaitGroup 任务合同的静态说明图，查看 Add、goroutine、Done 与 Wait 的职责边界，不是运行截图。

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

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

症状	通常原因	处理方式
`negative WaitGroup counter`	重复 Done、分支额外 Done，或根本没有对应 Add	让每个任务入口只有一个 Add，每个任务出口只有一个 Done
Wait 很快返回	Add 在新 goroutine 中，正向 Add 与 Wait 竞争	把 Add 移到 go 之前
Wait 永远不返回	某条 return 或错误分支漏掉 Done	在任务入口立刻 defer Done

一个容易忽视的坑是“主流程已经 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 负数 panic、Wait 早退和批次复用边界的静态结构说明图 — 图2：WaitGroup 常见故障边界说明图，区分计数不匹配、等待时序和批次复用，不是运行截图。

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