Go 并发中 sync.WaitGroup 使用不当导致死锁的解决方案-Golang-PHP中文网

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

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

在 Go 并发编程中，sync.WaitGroup 是协调多个 goroutine 执行完成的核心工具。但若使用不当——尤其是将其作为值参数传递给函数——极易触发 fatal error: all goroutines are asleep - deadlock!。该错误并非运行时崩溃，而是程序逻辑卡死：主 goroutine 在 wg.Wait() 处永久阻塞，而所有工作 goroutine 已退出，却从未调用真正的 wg.Done()。

问题根源在于你代码中的这行：

go MoveFile(src, dst, wg) // ❌ 错误：传入 wg 的副本！

sync.WaitGroup 是一个结构体，包含 noCopy, state1, state2 等字段。当以值方式传参时，Go 会复制整个结构体。这意味着：

Go语言（Golang）1.26.0

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

下载

主协程中的 wg 实例拥有自己的计数器（初始为 0）；
每个 MoveFile goroutine 接收到的是 wg 的独立副本；
defer wg.Done() 调用的是副本的 Done()，对主 goroutine 的 wg 计数器毫无影响；
最终 wg.Wait() 等待一个永远无法归零的计数器 → 死锁。

✅ 正确做法：*始终通过指针传递 `sync.WaitGroup`**，确保所有 goroutine 操作的是同一个实例：

func MoveWorksheets(worksheetList []string) {
    var wg sync.WaitGroup

    for _, worksheet := range worksheetList {
        wg.Add(1)
        // ✅ 传指针：&wg
        go MoveFile(src, dst, &wg)
    }
    wg.Wait() // 主 goroutine 等待真实计数器归零
}

// ✅ 参数类型改为 *sync.WaitGroup
func MoveFile(src, dst string, wg *sync.WaitGroup) error {
    defer wg.Done() // 调用的是原始 wg 的 Done()

    sfi, err := os.Stat(src)
    if err != nil {
        return err
    }
    if !sfi.Mode().IsRegular() {
        return fmt.Errorf("CopyFile: non-regular source file %s (%q)", sfi.Name(), sfi.Mode().String())
    }

    dfi, err := os.Stat(dst)
    if err != nil {
        if !os.IsNotExist(err) {
            return err
        }
    } else {
        if !dfi.Mode().IsRegular() {
            return fmt.Errorf("CopyFile: non-regular destination file %s (%q)", dfi.Name(), dfi.Mode().String())
        }
        if os.SameFile(sfi, dfi) {
            return nil
        }
    }

    return MoveFileContents(src, dst)
}

func MoveFileContents(src, dst string) error {
    if err := os.Rename(src, dst); err != nil {
        // ⚠️ 注意：log.Fatal 会终止整个进程！应返回错误供上层处理
        return fmt.Errorf("failed to rename %s → %s: %w", src, dst, err)
    }
    return nil
}

? 关键注意事项：