Go WaitGroup Add 为什么不能放在并发 goroutine 内

如果把 wg.Add(1) 写进即将启动的 goroutine，外层的 wg.Wait() 可能在这次 Add 发生前就看到计数器为 0，直接返回。更严重时，Add 还会与 Wait 并发，触发 sync: WaitGroup misuse: Add called concurrently with Wait。所以常规规则很简单：先在创建 goroutine 的代码中登记任务，再执行 go；任务结束时用 Done 抵消计数。

官方地址：https://pkg.go.dev/sync#WaitGroup

为什么 Add 放进 goroutine 会失去保证

WaitGroup 的核心不是“等待某个 goroutine”，而是维护一个任务计数器。计数器为 0 时，Wait 没有需要等待的任务；正数才表示还有任务未完成。把 Add 放进 goroutine 后，登记动作本身也变成了一个尚未确定何时发生的并发动作。

典型的错误写法如下：

var wg sync.WaitGroup

go func() {
	// 错误：登记动作晚于 goroutine 的创建，外层 Wait 可能先看到零值
	wg.Add(1)
	defer wg.Done()
	work()
}()

// 错误窗口：此时计数器仍可能是 0
wg.Wait()

这里有两种结果。第一种是主 goroutine 先执行 Wait，因为计数器还是 0，等待立即结束；随后子 goroutine 才调用 Add，任务已经脱离了这次等待。第二种是 Wait 已经建立等待关系，子 goroutine 再以正增量修改计数器，于是标准库会把它视为不安全的 Add/Wait 并发。

正确写法：先 Add，再创建 goroutine

把任务登记放在 go 语句前，外层代码就能在调用 Wait 前把计数器从 0 建立为正数：

var wg sync.WaitGroup

// 先登记一个任务，再创建 goroutine，避免 Wait 观察到零值
wg.Add(1)
go func() {
	// 无论 work 如何结束，都把任务计数减回去
	defer wg.Done()
	work()
}()

// 只有计数器归零后才返回
wg.Wait()

这不是为了让调度器“先运行 Add”，而是让 Add 在并发任务产生之前完成。官方文档也明确建议：当计数器为 0 时，正增量 Add 必须发生在 Wait 之前；通常意味着 Add 要放在创建 goroutine 或其它待等待事件之前。

动态创建任务时，什么时候还能继续 Add

“Add 必须在 goroutine 外”是最稳妥的初学者规则，但动态任务并不等于完全不能在并发函数中追加任务。关键边界是：WaitGroup 不能在计数器为 0 时与正增量 Add 争用。如果已有一个正数任务作为父任务，父任务内部可以继续登记子任务，并在父任务 Done 前保证这些子任务已经登记完成。

var wg sync.WaitGroup

// 先保留父任务，保证动态 Add 时计数器不是从零启动
wg.Add(1)
go func() {
	defer wg.Done()

	for _, item := range items {
		// 父任务仍在计数器中，子任务登记有明确的生命周期边界
		wg.Add(1)
		go func(item Item) {
			defer wg.Done()
			process(item)
		}(item)
	}
}()

wg.Wait()

实际工程中更推荐让“谁创建任务，谁负责 Add；谁完成任务，谁负责 Done”，并把任务列表在进入等待前固定下来。不要依赖“这次调度大概会先跑子 goroutine”的经验。

Go 1.25 以后可以考虑 WaitGroup.Go

当前官方 sync 文档提供了 WaitGroup.Go：它把 Add、创建 goroutine 和返回后的 Done 封装在一起，适合任务边界清楚的场景：

var wg sync.WaitGroup

// Go 负责登记任务、启动函数并在函数返回后调用 Done
wg.Go(func() {
	process(item)
})

// 等待 Go 登记的任务全部完成
wg.Wait()

WaitGroup.Go 不能让传入函数 panic；如果项目需要兼容没有该方法的旧 Go 版本，就继续使用显式的 Add/Done 写法。无论采用哪种 API，都要先确认“等待开始时，计数器已经代表了本轮任务集合”。

几个容易混淆的判断

• 不是所有 Add 都必须在主 goroutine：计数器已经大于 0 且生命周期由父任务托住时，可以动态追加，但边界要能证明。
• Done 不是启动信号：它只是 Add(-1)，应和一次成功的任务登记成对出现。
• 不要复制 WaitGroup：WaitGroup 应按指针语义共享，复制后各自维护计数器会让等待对象失去对应关系。

记住一句话：Wait 只看计数器，不会替你推测“马上要启动的 goroutine”。先登记，再并发；动态追加时保持计数器非零，并明确父子任务的完成边界。

常见问题

为什么有时错误写法也“看起来能跑”？

因为调度时序碰巧让子 goroutine 先执行了 Add，但这只是一次运行结果，不是 API 保证。换机器、换负载或加入日志后都可能改变顺序。

WaitGroup.Go 能不能替代所有 Add/Done？

不能。它适合由函数调用直接表达任务边界的场景；需要对批量任务、父子任务或旧版本 Go 做兼容时，显式 Add/Done 仍然更灵活。