Go sync.WaitGroup WaitGroup 为什么不能复制

很多 Go 并发问题并不是 Wait() 本身失效，而是 sync.WaitGroup 在已经使用后被悄悄复制了。复制发生后，调用方看到的是两个结构相同、状态却彼此独立的对象：一个副本可能在等待自己的计数，另一个对象却在接收 Done()。因此，官方文档要求 WaitGroup 首次使用后不得复制。

复制 WaitGroup 为什么会把同步状态拆开

WaitGroup 的零值可以直接使用，但它不是只保存一个普通整数。当前实现中包含用于禁止复制的 noCopy 标记、承载任务计数与等待者状态的原子状态，以及用于唤醒等待者的信号量。把已经调用过 Add、Done 或 Wait 的值复制出来，相当于把这组内部状态复制成两份。

这不是指针别名。下面的参数是值传递，进入函数时会产生一个新的 WaitGroup：

package main

import "sync"

// 错误示例：值参数会复制调用方的 WaitGroup。
func start(wg sync.WaitGroup) {
	// 这里的 Add 和 Done 作用在副本上，调用方看不到同一份计数。
	wg.Add(1)
	go func() {
		// 副本的计数归零，不代表调用方的计数也归零。
		defer wg.Done()
	}()
}

func main() {
	var wg sync.WaitGroup
	start(wg) // 传值复制，不能用来共享同步状态。
	wg.Wait()
}

即使某次运行看起来没有卡住，也不能把它当成安全证明。调度时机、计数初值和等待发生在哪个对象上，都会改变结果。

哪些复制位置最容易让 Wait 提前返回

最常见的风险不是显式写出 copy := original，而是让 Go 在语法背后替你复制。下面的检查表适合做代码审查入口：

典型症状是 Wait 提前返回、某个等待永远不结束，或者 go vet 报告 copylocks。根因是参与 Add、Done、Wait 的对象身份不一致，而不是给 Wait 加重试。

正确写法是让所有参与方共享一个指针

最小修复是把共享对象声明在调用方，再把指针传给需要注册任务的函数。Add(1) 放在创建 goroutine 之前，任务结束时用 defer wg.Done() 对同一个实例减计数：

package main

import "sync"

// 指针参数让注册任务和等待操作使用同一个 WaitGroup。
func start(wg *sync.WaitGroup) {
	// 先增加计数，再创建 goroutine，避免 Wait 看到零计数而提前返回。
	wg.Add(1)
	go func() {
		// 无论任务如何正常返回，都对同一个实例执行 Done。
		defer wg.Done()
		// 这里放实际工作；发生错误时也不能漏掉 Done。
	}()
}

func main() {
	var wg sync.WaitGroup
	start(&wg) // 传递地址，不复制同步状态。
	wg.Wait() // 等待同一实例的计数归零。
}

如果外层类型包含 WaitGroup，也应让会修改同步状态的方法使用指针接收者：

type Worker struct {
	wg sync.WaitGroup
}

// 指针接收者避免调用方法时复制 Worker 及其中的 WaitGroup。
func (w *Worker) Start() {
	w.wg.Add(1)
	go func() {
		// 延迟调用必须落在 w.wg 这个原实例上。
		defer w.wg.Done()
	}()
}

用 go vet 把按值复制拦在提交前

在项目根目录执行 go vet ./...，重点关注值参数、值接收者、赋值、返回值以及包含同步原语的容器。copylock 分析器会把按值传递可能造成的锁类复制报告出来；较新的 Go 工具链还提供针对 WaitGroup.Add 调用位置的检查。

# 检查整个模块，优先处理 copylocks 和 WaitGroup 相关提示
go vet ./...

提交前可以按下面的顺序人工确认：第一，WaitGroup 是否只在一个明确的生命周期内使用；第二，所有方法是否通过指针访问包含它的结构体；第三，Add 是否早于对应的 goroutine；第四，复用同一个 WaitGroup 时，上一轮 Wait 是否已经返回。若确实要开始一批独立任务，应重新声明一个新的 WaitGroup，而不是复制旧对象。

常见问题

WaitGroup 在第一次使用前可以复制吗？

语言层面可以复制零值，但复制后的对象从此是两份独立状态。为了避免以后某处先使用一个、再误用另一个，工程代码仍建议从一开始就用指针管理共享实例。

把 WaitGroup 放进结构体就一定错吗？

不一定。结构体可以拥有 WaitGroup，但不要复制这个结构体；通常使用指针接收者，并避免按值返回或按值传参。

重新开始一批任务时能不能复用原 WaitGroup？

可以复用同一个实例，但必须等上一轮 Wait 返回后再开始新的 Add。如果生命周期更清晰，重新声明一个零值 WaitGroup 也更容易审查。