Go WaitGroup 为什么出现 negative WaitGroup counter

看到 panic: sync: negative WaitGroup counter 时，先不要给 Wait() 加超时或继续增加 Add(1)。它表示同一个 sync.WaitGroup 的任务计数已经被减到了 0 以下，最常见原因是某条路径重复调用了 Done()，或者根本没有为这次任务成功配对 Add(1)。修复重点是让每个任务只有一个计数来源和一个退出扣减点。

WaitGroup 的计数到底记录什么

WaitGroup 记录的是“尚未完成的任务数”，不是 goroutine 数量，也不是 Wait() 调用次数。Add(n) 增加任务数，Done() 扣减一个任务，Wait() 只负责等待计数归零。

因此，下面的代码会把计数从 1 减成 0，再减成 -1：

package main

import (
    "sync"
)

func main() {
    var wg sync.WaitGroup
    wg.Add(1) // 只登记一个任务，计数从 0 变为 1
    wg.Done() // 第一次扣减后计数归零
    wg.Done() // 第二次扣减使计数为负数，触发 panic
    wg.Wait() // 这里不会成为修复点，panic 已经在 Done 中发生
}

官方实现会在 Add 处理负向变化后检查计数；而 Done 本身就是 Add(-1)。所以日志里虽然常出现“Done 调用”，真正要检查的是所有可能走到扣减点的路径。

三个高频原因：重复 Done、漏 Add 和提前 Wait

第一类是同一任务同时有“统一收尾”和“分支收尾”。例如函数开头已经 defer wg.Done()，错误分支又手写一次 wg.Done()。解决方案是让退出扣减只存在于一个位置：

func worker(wg *sync.WaitGroup, jobs 

第二类是调用者启动了一个 goroutine，却没有先执行对应的 Add(1)，或者把 Add 放进 goroutine 后才调用 Wait。第三类是循环复用同一个组：上一轮 Wait 尚未返回，下一轮又在计数为零的窗口里并发增加任务。Go 官方要求计数器为零时的正向 Add 发生在 Wait 之前；批次复用则要等上一轮 Wait 返回。

用最小检查清单定位是哪一次扣过头

排障时不要先给计数器“补一笔”。在创建任务的同一处登记，在 goroutine 入口立即绑定一次 defer Done，并把任务编号带进日志：

for id, job := range jobs {
    wg.Add(1) // 在创建 goroutine 前登记，避免 Wait 看到零计数
    go func(id int, job Job) {
        defer wg.Done() // 每个 goroutine 只绑定一个退出扣减
        log.Printf("worker start id=%d", id)
        if err := handle(job); err != nil {
            log.Printf("worker stop id=%d err=%v", id, err) // 记录失败，不重复 Done
            return
        }
        log.Printf("worker finish id=%d", id)
    }(id, job)
}
wg.Wait() // 所有 Add 已完成后再等待本批任务归零

什么时候改用 WaitGroup.Go

如果项目使用的 Go 版本提供 WaitGroup.Go，它可以把“启动 goroutine 与增加计数”组合起来，减少漏写 Add 的机会；但任务函数仍应拥有清晰的返回边界，不能在外层再额外调用 Done。需要兼容旧版本时，沿用 Add(1) 加单个 defer Done() 的写法即可。

相关问题

Done 和 Add(-1) 有区别吗？

在计数效果上没有区别，Done() 就是 Add(-1)。语义上使用 Done 更能表达“当前任务结束”，也更容易检查一进一出是否配对。

把 Add(1) 放到 goroutine 内为什么不稳？

外层可能先执行 Wait()，此时计数仍是 0，等待会直接结束；随后 goroutine 才增加计数，批次边界已经失效。应在创建 goroutine 前登记。

WaitGroup 能跨多轮任务复用吗？

可以，但必须等上一轮 Wait() 返回后再开始下一轮正向 Add，并确保上一轮没有残留任务。复杂批处理通常为每轮创建新的 WaitGroup，更容易维护。