Go 并发编程中 sync.WaitGroup 死锁问题的根源与解决方案-Golang-PHP中文网

Go 并发编程中 sync.WaitGroup 死锁问题的根源与解决方案

本文详解 go 中因错误传递 sync.waitgroup 值类型参数导致“all goroutines are asleep - deadlock”错误的根本原因，并提供正确用法、代码修复示例及最佳实践。

本文详解 go 中因错误传递 sync.waitgroup 值类型参数导致“all goroutines are asleep - deadlock”错误的根本原因，并提供正确用法、代码修复示例及最佳实践。

在 Go 并发编程中，sync.WaitGroup 是协调多个 goroutine 执行完成的常用工具。但若使用不当——尤其是将其以值类型（value）方式传入 goroutine——将引发致命死锁：程序运行结束后报错 fatal error: all goroutines are asleep - deadlock!。该错误并非逻辑崩溃，而是调度器检测到所有 goroutine 已阻塞且无唤醒可能，被迫中止。

问题核心在于：sync.WaitGroup 是一个包含互斥锁和计数器的结构体，必须通过指针传递，否则每个 goroutine 收到的是其独立副本，wg.Done() 修改的是副本中的计数器，而主 goroutine 调用 wg.Wait() 等待的仍是原始 WaitGroup 的计数器（始终为初始值或未被正确递减），最终永远阻塞。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。

下载

以下为原始代码的问题定位与修复：

❌ 错误写法（触发死锁）

func MoveWorksheets(worksheetList []string) {
    var wg sync.WaitGroup
    for _, worksheet := range worksheetList {
        wg.Add(1)
        go MoveFile(src, dst, wg) // ⚠️ 传值！创建 wg 副本
    }
    wg.Wait() // 永远等待，因副本中的 Done() 不影响此 wg
}

func MoveFile(src, dst string, wg sync.WaitGroup) { // 参数是值类型
    defer wg.Done() // 修改的是副本，主 wg 计数器不变
    // ... 文件操作
}

✅ 正确写法（消除死锁）

func MoveWorksheets(worksheetList []string) {
    var wg sync.WaitGroup
    for _, worksheet := range worksheetList {
        wg.Add(1)
        go MoveFile(src, dst, &wg) // ✅ 传指针！共享同一实例
    }
    wg.Wait()
}

func MoveFile(src, dst string, wg *sync.WaitGroup) { // 参数改为 *sync.WaitGroup
    defer wg.Done() // 正确修改原始 wg 的计数器
    // ... 文件操作（注意：src/dst 需在循环内正确捕获，见下方补充）
}

⚠️ 重要补充：循环变量捕获问题
上述修复虽解决 WaitGroup 死锁，但还存在经典闭包陷阱：src 和 dst 若为循环外变量或未显式捕获，所有 goroutine 可能共享同一份值（如最后迭代的 src/dst）。推荐写法：

for _, worksheet := range worksheetList {
    wg.Add(1)
    worksheet := worksheet // 显式创建局部变量，避免闭包引用
    go func() {
        defer wg.Done()
        // 在此处使用 worksheet 构造 src/dst
        src := "path/to/" + worksheet + ".xlsx"
        dst := "backup/" + worksheet + ".xlsx"
        MoveFileContents(src, dst) // 或封装完整逻辑
    }()
}