WaitGroup 是用于等待多个 goroutine 完成的同步原语，必须在启动 goroutine 前调用 Add()，goroutine 内用 defer wg.Done()，主线程调用 Wait()；不可复制、需传指针，常与 context.WithTimeout 配合防死锁。
WaitGroup 是什么，什么时候必须用它
当多个 goroutine 并发执行、且主 goroutine 需要等待它们全部结束才能继续时，sync.WaitGroup 是最直接可靠的同步手段。它不是用来保护共享数据的（那是 sync.Mutex 的事），而是用来“计数+阻塞等待”的。如果你写了 go func() { ... }() 但没等它们跑完就退出了，程序大概率提前结束——这时你就需要 WaitGroup。
正确初始化和调用 Add/Done/Wait 的顺序
WaitGroup 必须在启动 goroutine 前调用 Add()，且不能在 goroutine 内部调用 Add() 后再调用 Done() ——除非你明确控制好竞态（不推荐）。常见错误是把 Add() 放在 go 语句之后，导致 Wait() 立即返回（因为计数还没加）或 panic（Add 被并发调用）。
-
Add()必须在go语句之前，或至少确保在任何Done()之前被调用一次 -
Done()应该在 goroutine 结束前调用，通常放在函数末尾或 defer 中 -
Wait()只能在主线程（或需等待的 goroutine）中调用，且只能等一次；重复调用不会报错但无意义
package main
<p>import (
"fmt"
"sync"
"time"
)</p><p>func main() {
var wg sync.WaitGroup</p><pre class='brush:php;toolbar:false;'>for i := 0; i < 3; i++ {
wg.Add(1) // ✅ 必须在 go 前
go func(id int) {
defer wg.Done() // ✅ 推荐用 defer，确保执行
fmt.Printf("goroutine %d running\n", id)
time.Sleep(time.Second)
}(i)
}
wg.Wait() // ✅ 主线程阻塞等待全部完成
fmt.Println("all done")}
WaitGroup 不能跨协程复用，也不能复制传递
sync.WaitGroup 是一个包含 mutex 和 counter 的结构体，它**不可拷贝**。如果你把它作为参数传给函数并试图在函数内修改（比如调用 Add()），又或者在多个地方赋值（wg2 := wg），Go 编译器会报错：cannot assign to struct containing sync.WaitGroup 或运行时报 data race。必须传指针，且所有操作都应针对同一个地址。
立即学习“go语言免费学习笔记（深入）”；
- 函数接收
*sync.WaitGroup，而不是sync.WaitGroup - 不要在 map、slice 中存 WaitGroup 实例（会触发复制）
- 不要在循环中反复声明新 WaitGroup 来“重用”，应该复用同一个实例（调用前确保已 Wait 完）
WaitGroup 和 context.WithTimeout 搭配使用更健壮
WaitGroup.Wait() 是永久阻塞的，一旦某个 goroutine 卡住或死锁，整个程序就卡死。生产环境强烈建议加超时控制。常见做法是用 context.WithTimeout 启动一个 select 监听 done 通道和超时信号。
package main
<p>import (
"context"
"fmt"
"sync"
"time"
)</p><p>func main() {
var wg sync.WaitGroup
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()</p><pre class='brush:php;toolbar:false;'>wg.Add(1)
go func() {
defer wg.Done()
time.Sleep(5 * time.Second) // 故意超时
fmt.Println("this won't print")
}()
done := make(chan struct{})
go func() {
wg.Wait()
close(done)
}()
select {
case <-done:
fmt.Println("all finished")
case <-ctx.Done():
fmt.Println("timeout waiting for goroutines")
}}
真正容易被忽略的是：WaitGroup 本身不提供取消能力，也不感知上下文取消。它的职责就是计数，超时、中断、错误传播这些都得靠外层机制补足。别指望靠 WaitGroup 解决所有并发协调问题。
