Go goroutine 泄漏怎样从阻塞点开始排查

Go goroutine 泄漏通常不是“创建太多”这么简单，而是某个 goroutine 已经停在接收、发送、加锁或 I/O 等阻塞点，却再也等不到解除条件。排查时先记录数量是否在相同业务操作结束后仍持续增加，再抓一份 goroutine profile；栈里重复出现的阻塞函数和代码行，往往比先调并发参数更接近根因。

官方文档：https://pkg.go.dev/runtime/pprof

HTTP 采集入口：https://pkg.go.dev/net/http/pprof

先把数量增长和真正泄漏分开

runtime.NumGoroutine() 只能告诉你当前数量，不能单独证明泄漏。一次高峰请求会暂时创建很多工作 goroutine；如果请求完成后数量回落，通常是正常波动。更值得关注的是同一操作重复执行后，基线一轮比一轮高，且这些 goroutine 长时间停在同一个阻塞点。

可以先按三个问题缩小范围：

• 触发一次任务后，任务已经返回，相关 goroutine 是否仍然存在？
• 多次触发同一任务，数量是否按近似固定的增量增长？
• 栈显示的发送、接收、锁等待或 I/O，是否还有任何代码能够让它继续？

只有“任务已结束、数量不回落、解除条件不可达”同时出现，才应优先按泄漏处理。否则可能只是工作池、连接等待或调度高峰，不要直接把所有阻塞都当成泄漏。

用 goroutine profile 找到阻塞点

服务已经接入 pprof 时，可以从默认 ServeMux 暴露调试端口，再读取 goroutine profile。debug=2 返回更接近 panic 栈的可读文本，适合第一轮肉眼定位；默认的二进制 profile 则适合交给 go tool pprof 做聚合分析。

import (
    "log"
    "net/http"
    _ "net/http/pprof" // 注册 /debug/pprof/ 下的标准分析入口
)

func startDebugServer() {
    // 调试端口只绑定本机，避免把未鉴权的诊断入口暴露到公网。
    go func() {
        if err := http.ListenAndServe("127.0.0.1:6060", nil); err != nil {
            log.Printf("pprof server stopped: %v", err)
        }
    }()
}

采集时可先保存文本栈，再按函数名、包名和代码行聚类：

# 读取当前所有 goroutine 的可读栈，便于先找重复阻塞点
curl -o goroutines.txt 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2'

# 下载 profile 后交给 pprof 聚合调用栈
go tool pprof 'http://127.0.0.1:6060/debug/pprof/goroutine'

看到大量栈停在 ch 、、sync.(*Mutex).Lock、WaitGroup.Wait 或网络读取处时，不要只看这一行。继续向上看是谁创建了 goroutine，向下确认它等待的对象是谁持有，以及任务结束时是否有取消、关闭或释放动作。

如果不方便开放 HTTP 入口，也可以在受控的诊断代码中直接写出 profile：

import (
    "os"
    "runtime/pprof"
)

func dumpGoroutines(path string) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    // Close 由当前函数负责，避免诊断文件句柄也变成资源泄漏。
    defer f.Close()

    // debug=2 输出带函数名和代码行的 goroutine 栈。
    return pprof.Lookup("goroutine").WriteTo(f, 2)
}

沿阻塞操作回看退出条件

定位到阻塞行后，按阻塞对象建立一条“谁等待、谁解除、何时退出”的链路。常见情况如下：

例如，生产者提前返回而消费者仍在等待，就应让消费者同时监听取消信号；不要假设“以后总会有人发送”。下面的结构把正常数据和退出信号放在同一个选择点：

func consume(ctx context.Context, jobs 

修复后用同一阻塞点复盘

修复的目标不是让某一刻的 goroutine 总数变小，而是让一条业务操作结束后，相关 goroutine 能沿同一条退出路径收敛。复盘时重复相同的触发条件，比较两份 profile：原来反复出现的阻塞栈是否消失，剩余栈是否属于常驻 worker、HTTP server 或其他有明确生命周期的 goroutine。

如果使用较新的 Go 版本，还可以关注 goroutineleak profile。它针对被并发原语永久阻塞、且解除条件不可达的一类泄漏；但它不能替代普通 goroutine profile，因为网络 I/O、生命周期设计错误和仍可能解除的长等待仍需要结合代码判断。

最终可以把排查闭环压缩成四句话：

1. 先看同一任务完成后数量是否回落。
2. 再抓 profile，按重复阻塞函数和代码行聚类。
3. 沿创建者、等待对象和解除者回看生命周期。
4. 修复取消、关闭、Done 或 deadline 后，用同一场景再次对比。

常见问题

goroutine 卡在 IO wait 就一定是泄漏吗？

不一定。网络轮询本身可以是正常等待，关键是请求是否有明确超时、取消和连接关闭路径；只有等待条件在生命周期结束后仍不可达，才更像泄漏。

为什么只看 NumGoroutine 不够？

它只有数量没有调用栈，无法区分正常常驻 worker、短暂高峰和重复卡死的业务 goroutine。数量应当用来发现趋势，profile 才用来定位阻塞点。