Go WaitGroup Add 放错位置为什么会 panic

我排查 WaitGroup 问题时，最容易误判的一点是：看到 goroutine 里有 Add(1)，并不代表每次都会立刻 panic。更常见的第一层问题是 Wait() 看到计数仍为 0，先返回；等新 goroutine 稍后执行 Add，程序已经失去了“这一批任务都已登记”的边界。随后如果又发生多次 Done()、重复复用等待组，才会进一步出现计数为负或 Add 与 Wait 并发的运行时 panic。

这篇只处理一个边界：如何安排 sync.WaitGroup.Add、启动 goroutine 和 Wait 的位置。结论很简单：正数 Add 在计数为 0 时必须先于 Wait，通常也应先于创建要等待的 goroutine。

先看清 panic 背后的计数边界

WaitGroup 不是锁，也不会替你记录“已经创建了多少个 goroutine”。它只有一个任务计数器：Add 增加计数，Done 等价于 Add(-1)，Wait 等到计数回到 0。计数变成负数会 panic；在计数为 0 的等待窗口里并发增加正数，也会让 Add 与 Wait 的协议失效。

下面这种写法把登记动作交给了新 goroutine：

var wg sync.WaitGroup
go func() {
    // 这里登记得太晚，Wait 可能先看到零计数并直接返回。
    wg.Add(1)
    // 退出时只抵消本 goroutine 已经登记的任务。
    defer wg.Done()
    work()
}()
wg.Wait()

它至少有两个风险。第一，主 goroutine 可能在新 goroutine 获得调度前就执行 Wait，导致“任务还没开始登记，等待已经结束”。第二，如果外层还有一次 Add、一次 Done，或者等待组被下一轮复用，计数的所有权会变得不清楚，容易触发 sync: negative WaitGroup counter 或 sync: WaitGroup misuse。

我现在固定使用的写法：先登记，再启动

对一个明确数量的任务，先把计数器设好，再创建 goroutine。这样 Wait 的入口就有确定的正数计数，不依赖调度顺序：

var wg sync.WaitGroup

// 先登记任务数量，再创建 goroutine，避免 Wait 看到零计数。
wg.Add(1)
go func() {
    // defer 保证正常返回和提前 return 都会归还计数。
    defer wg.Done()
    work()
}()

// 只有计数归零后才继续执行。
wg.Wait()

这里的关键不是“Add 必须紧挨着 go”，而是正数 Add 必须建立在 Wait 之前的任务集合中。defer Done 也要放在 goroutine 入口附近，避免中间新增返回分支后忘记归还计数。

批量任务和等待组复用时，最容易踩的两个坑

循环启动任务时，把每轮的 Add 放在循环体内、把对应的 Done 放在任务函数内即可；不要把 Add 再包进任务函数。若任务数量在运行期间动态产生，必须把“谁负责产生新任务、何时允许 Wait”设计成明确协议，而不是让任意 worker 随时对一个已经可能归零的等待组 Add。

var wg sync.WaitGroup
for _, job := range jobs {
    // 每个任务在启动前登记一次，循环变量复制到参数避免捕获歧义。
    wg.Add(1)
    go func(job Job) {
        // 无论处理成功还是失败，都要归还本次计数。
        defer wg.Done()
        process(job)
    }(job)
}

// 这一批任务的 Add 已全部完成后再等待。
wg.Wait()

复用同一个 WaitGroup 时，下一批正数 Add 要等上一轮 Wait 返回；否则上一轮计数还在归零过程中，新的任务集合与旧集合会混在一起。若使用 Go 1.25 或更新工具链，也可以了解 WaitGroup.Go 这个封装，但仍要保持“任务登记和启动属于同一协议”的思路。

提交前用 go vet 把明显误用拦下来

Go 1.25 起，go vet 包含 waitgroup 分析器，会报告把 WaitGroup.Add 放在新 goroutine 内的典型写法。它不能证明所有动态并发协议都正确，但适合做第一道廉价检查：

# 在模块根目录检查典型的 goroutine 内 Add 误用。
go vet ./...

最后可以按这张清单复盘：正数 Add 是否先于 Wait；每个 Add 是否只有一个对应的 Done；Done 是否覆盖错误返回路径；等待组是否在上一轮 Wait 返回后才复用；动态生产任务时，是否有明确的停止和等待协议。只要这几项能回答清楚，panic 通常就不再是靠“多加一个 sleep”来碰运气修复。

相关问题

WaitGroup.Add 放在 goroutine 外就绝对不会 panic 吗？ 不绝对。重复 Done、Add(-1) 过多、复制已经使用过的 WaitGroup，仍可能触发 panic；先登记只是消除了最典型的 Add/Wait 竞态。

为什么有时错误写法也能通过测试？ 因为调度顺序可能刚好让 goroutine 先运行，Wait 没有提前返回。通过一次测试只能说明这次时序没有暴露问题，不能把它当成并发协议成立的证明。