Go 1.27 goroutine leak profile 如何读取新增诊断字段

服务里的 goroutine 数量一直涨，并不等于每个 goroutine 都泄漏：高流量时的临时阻塞、网络 IO 等待和真正“永远醒不过来”的任务，应该分开判断。Go 1.27 把 goroutineleak profile 正式加入 runtime/pprof，可以从运行中的服务筛出一类永久阻塞的 goroutine，再用 pprof 输出里的字段落到具体源码行。

官方资料：https://go.dev/doc/go1.27

Go 1.27 的 goroutineleak 到底报告什么

这个 profile 报告的是已经发生、且运行时判断无法再被并发原语唤醒的 goroutine。判断依赖 GC 的可达性：如果 goroutine 卡在 channel、sync.Mutex、sync.RWMutex、sync.WaitGroup 或 sync.Cond 上，而阻塞它的原语不再能从活跃 goroutine 的引用链到达，它就可能进入泄漏集合。

因此，goroutine profile 与 goroutineleak 不是一回事。前者列出当前所有 goroutine，后者只筛选运行时能证明为永久阻塞的那一部分；普通网络读、文件读、系统调用和自定义自旋锁，不在这套检测范围内。

从 pprof 入口采集一份可读 profile

已有 net/http/pprof 的服务无需额外注册新 handler；Go 1.27 会提供 /debug/pprof/goroutineleak。下面的示例故意让一批 worker 向无缓冲 channel 发送结果，但接收方在遇到错误时提前返回，剩余发送者就失去了未来的接收者。

package main

import (
    "errors"
    "log"
    "net/http"
    _ "net/http/pprof"
    "time"
)

type task struct{ id int }

func handle(t task) error {
    time.Sleep(20 * time.Millisecond)
    if t.id == 3 {
        return errors.New("temporary task error")
    }
    return nil
}

func runBatch(tasks []task) error {
    resultCh := make(chan error)
    for _, t := range tasks {
        current := t
        go func() {
            // 发送端没有缓冲；接收方提前返回后，这里会永久等待。
            resultCh 

编译并运行后，等程序产生几轮错误，再把 profile 保存到本地：

# 下载泄漏 profile，不把它和普通 goroutine profile 混淆
curl -s http://127.0.0.1:6060/debug/pprof/goroutineleak > leak.prof

# 进入交互模式，随后可用 list 函数名查看源码行
go tool pprof leak.prof

采集依赖一次完成的 GC 周期；刚启动、尚未形成稳定阻塞关系时，结果可能为空或数量很小。可以隔一段时间重复采集，但不要把“第一次没有报告”当成没有泄漏。

读取 Type、Total 和源码行

在 pprof 交互模式里执行 list runBatch，重点看下面几类信息。它们不是让你猜原因的装饰字段，而是一条从“报告是什么”走到“哪一行卡住”的证据链。

Type: goroutineleak
(pprof) list runBatch
Total: 8
ROUTINE ======================== main.runBatch.func1 in .../main.go
         0          8 (flat, cum)   100% of Total
         .          8    31: resultCh 

这里真正有价值的是最后一行：多个泄漏 goroutine 都停在发送操作，说明接收端的生命周期先结束了。不要只盯着 Total 做告警；ROUTINE 和源码行才告诉你该检查哪个 channel、哪个返回分支或哪个锁的释放路径。

先修复阻塞，再做一次复查

修复方向取决于通信协议。上例可以让结果 channel 具备足够容量，使 worker 在调用方提前返回后仍能完成一次发送；更稳妥的工程方案通常是给 worker 增加取消信号，并让发送使用可退出的 select。如果是后台循环，则要把 Start 与 Stop 设计成明确的生命周期，而不是把关闭责任藏在接口实现里。

func runBatchSafely(tasks []task) error {
    resultCh := make(chan error, len(tasks))
    for _, t := range tasks {
        current := t
        go func() {
            // 缓冲保证每个 worker 至少能交付一次结果，不依赖调用方继续接收。
            resultCh 

改完后再次采集 profile，检查 Total 是否停止增长，并确认原来的发送源码行不再出现。若 profile 仍有结果，再沿新的 ROUTINE 检查是否是另一条路径；修复一个泄漏点，不代表整个服务的并发协议已经闭合。

常见问题

为什么普通 goroutine profile 有很多阻塞，而 goroutineleak 没有？

普通 profile 记录当前 goroutine；goroutineleak 需要运行时判断阻塞条件永远不会满足，所以暂时等待的 worker 不会自动被算成泄漏。

网络 IO 卡住能被这个 profile 找到吗？

不能直接依赖它。官方定义的检测范围集中在 channel、阻塞 select 和指定的 sync 原语；网络或文件 IO 应结合超时、指标和普通 goroutine profile 排查。

Total 变大就一定是代码回归吗？

不一定。它是某个时刻的泄漏快照数量，先结合采集时间、流量和发布版本，再看同一 ROUTINE 是否持续累积。

为什么修复后第一次采集仍可能有旧结果？

旧 goroutine 只有在真正退出或不再满足泄漏判定后才会消失；等待一个合理的 GC 与业务周期，再按同一 URL 重新采集比较。

Go 1.27 的变化重点不是凭一个数字自动修复并发 bug，而是把一类过去需要人工从普通堆栈中筛选的问题，变成了可以定向采集、按字段阅读、回到源码行验证的诊断流程。