waitgroup.add() 必须在 goroutine 启动前调用且与 defer wg.done() 成对出现，避免计数错乱；channel 由生产者关闭并置于 wg.wait() 前；waitgroup 需以指针传递防止值复制；子 goroutine 应 defer wg.done() 并统一处理 context 超时。
WaitGroup.Add() 在循环中被多次调用导致计数错乱
常见现象是程序卡在 WaitGroup.Wait() 不返回，且 CPU 占用极低 —— 典型死锁信号。根本原因不是 WaitGroup 本身有问题，而是 WaitGroup.Add(1) 被放在了 goroutine 启动前的循环体里，但实际 goroutine 并未全部成功启动（比如因 channel 阻塞、panic 或提前 return），导致 WaitGroup.Done() 调用次数少于 Add() 次数。
实操建议：
- 确保
WaitGroup.Add(1)和defer wg.Done()成对出现在同一 goroutine 内部，且Add()必须在go语句之前执行 - 避免在 for 循环外一次性
wg.Add(len(tasks))，除非你能 100% 确保每个 task 都会触发 goroutine 启动并最终调用Done() - 在启动 goroutine 前加日志或断点，确认所有预期 goroutine 确实已创建（可用
runtime.NumGoroutine()辅助观察）
sync.WaitGroup 与 channel 关闭顺序引发的竞态
Composer 镜像同步常配合 channel 分发任务（如包名列表），若在所有 goroutine 启动后立即 close(ch)，而某个 goroutine 还没来得及从 channel 读取就退出，就会漏掉任务；更危险的是，如果 close(ch) 放在 wg.Wait() 之后，而消费者 goroutine 依赖 channel 接收信号来决定是否调用 Done()，就会形成等待闭环。
实操建议：
- channel 应由生产者关闭，且必须在所有发送操作完成后、任何
wg.Wait()之前关闭 - 消费者端用
for val := range ch自动感知关闭，不要手动判断ok后再调用Done()—— 这容易遗漏最后一次迭代 - 若需在消费者内做额外清理，把
defer wg.Done()放在函数最顶部，而不是range循环结束之后
WaitGroup 被跨 goroutine 复制导致计数失效
Go 中 struct 是值传递。如果把 sync.WaitGroup 作为参数传给函数，或在闭包中隐式捕获，实际上传递的是副本。此时调用 wg.Add() 或 wg.Done() 操作的是副本，主 goroutine 的原始 wg 计数永远为 0，Wait() 无限阻塞。
实操建议：
- 永远以指针形式使用：
&wg传参，函数签名接收*sync.WaitGroup - 检查所有闭包引用：若在
for range中启动 goroutine 并引用外部wg，确保它是地址，而非变量名直接写在 go 语句里（例如go func(wg *sync.WaitGroup) { ... }(wg)） - 启用
-race编译运行，这类复制问题会被竞态检测器直接标出
context.Context 超时未与 WaitGroup 协同导致假死
镜像同步可能设置 context.WithTimeout 控制整体耗时，但若只用 select 监听 ctx.Done() 而忽略 WaitGroup 状态，会出现两种情况：一是超时后主 goroutine 退出，但子 goroutine 仍在运行（资源泄漏）；二是子 goroutine 检测到 ctx 超时后自行 return，却忘了调用 wg.Done()，导致 Wait() 永不返回。
实操建议：
- 每个子 goroutine 必须保证：无论正常结束、错误退出还是 ctx 取消，都执行一次
wg.Done() - 推荐模式：在 goroutine 入口处
defer wg.Done()，并在内部用select判断 ctx 是否完成，完成则 return —— defer 仍会执行 - 避免在
select的case 分支里再调用 <code>wg.Done()，会造成重复计数
WaitGroup 本身足够简单，死锁几乎全是使用者对“计数守恒”理解偏差造成的。最易被忽略的是 defer 的执行时机和值传递陷阱 —— 它不会报错，只会让程序停在那儿，等你花半小时看 goroutine stack 才发现 wg 计数还是 0。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
