sync.WaitGroup 死锁常见原因解析

本文深入剖析了 Go 语言中 sync.WaitGroup 导致死锁的四大高频陷阱：值传递使 Done() 完全失效、defer wg.Done() 位置不当导致提前退出时未执行、向无缓冲 channel 发送数据前未启动接收 goroutine，以及 Add() 与 Done() 调用次数不匹配；这些错误往往隐蔽且易叠加，仅靠逻辑推演难以发现，必须依赖 go vet 静态检查、-race 竞态检测，并严格遵循指针传递、首行 defer、先启 receiver、循环内即时 Add 等实践准则——掌握这些，才能真正避开并发协作中最令人抓狂的“永远等待”。

WaitGroup 值传递导致 Done() 无效

这是最隐蔽也最常踩的坑：把 sync.WaitGroup 当作普通结构体按值传入 goroutine，比如 go downloadFile(url, wg)。Go 会复制整个结构体，而 sync.WaitGroup 内部包含 sync.Mutex 和计数器字段，副本间的互斥锁和计数器完全独立。子 goroutine 调用 wg.Done() 只是减少副本计数，main 中的原始 wg.Wait() 永远等不到计数归零。

• 运行 go vet 会直接报错：passes sync.WaitGroup by value
• 必须改为指针传递：go downloadFile(url, &wg)，且函数签名要声明为 func downloadFile(url string, wg *sync.WaitGroup)
• IDE（如 GoLand、VS Code + gopls）通常会在参数位置标黄并提示 “contains sync.Locker”

defer wg.Done() 放错位置，提前 return 导致未执行

defer wg.Done() 如果写在函数中间或末尾，一旦前面有 return err 或 panic，它根本不会触发。尤其在文件下载、HTTP 请求这类易出错场景中，http.Get 失败、os.Create 权限不足、io.Copy 中断都会让函数提前退出，Done() 就永远卡住。

• 正确做法：把 defer wg.Done() 放在函数**第一行**，确保无论从哪条路径退出都执行
• 不要依赖“逻辑上一定会走到最后”，并发代码的错误路径比想象中更常见
• 配合 if err != nil 的早期返回，能显著降低遗漏 Done() 的风险

向无缓冲 channel 发送数据，但没人接收

当 WaitGroup 和 channel 混用时，典型死锁链是：goroutine 向 out 发送结果 → 因 out 是无缓冲通道且无人接收而阻塞 → defer wg.Done() 不执行 → wg.Wait() 永不返回。主 goroutine 还没开始读 out，所有 worker 就已卡死在发送端。

• 修复核心：确保发送端永远有接收者 —— 必须启动一个**独立 goroutine** 专门消费 out
• 不能把接收逻辑放在 wg.Wait() 之后，那已经太晚；必须在启动 worker 前就启动 receiver
• 如果要用带缓冲通道缓解，缓冲大小必须 ≥ 并发数，否则仍有概率阻塞（不推荐，掩盖问题而非解决）

Add() 和 Done() 数量不匹配

常见于循环外一次性 wg.Add(len(urls))，但实际只启动了 1 个处理 goroutine；或在 for 循环里漏掉 wg.Add(1)；又或者多个 goroutine 共享同一个 Done() 调用（比如用闭包捕获循环变量导致多次调用同一 Done()）。WaitGroup 计数器不是“任务完成数”，而是“尚未完成的 goroutine 数”。

• 原则：每个 goroutine 生命周期必须严格对应一次 wg.Add(1) + 一次 wg.Done()
• 避免在循环外统一 Add，改在每次 go func() 前立刻 wg.Add(1)
• 闭包捕获循环变量（如 for _, u := range urls { go func() { ... }() }）会导致所有 goroutine 共享同一个 u，进而可能重复调用或跳过 Done() —— 正确写法是 go func(u string) { ... }(u)

真正难调试的不是单个错误，而是多个陷阱叠加：比如值传递 + defer 位置错误 + 无缓冲 channel —— 这时 go run -race 和 go vet 是唯二靠谱的防线，别靠肉眼猜。

今天关于《sync.WaitGroup 死锁常见原因解析》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！