waitgroup 值传递导致 done() 无效：必须用指针传递；defer wg.done() 应置于函数首行；无缓冲 channel 需提前启动接收 goroutine；add() 与 done() 必须一一对应。
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 向 <code>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 是唯二靠谱的防线，别靠肉眼猜。
