Go goroutineleak 为什么画像没有发现全部阻塞（参数形态）

先给结论：Go 1.27 的 goroutineleak 画像不是“所有阻塞 goroutine 列表”。它只报告运行时能够证明为永久泄漏的一部分 goroutine：目标必须阻塞在 Go 的并发原语上，而且阻塞它的原语不能再从任何可运行 goroutine 的可达对象中找到。只要其中一个条件不满足，画像里没有它并不代表代码没有问题。

官方资料入口：https://go.dev/blog/goroutine-leak-profiles；版本说明：https://go.dev/doc/go1.27。本文只讨论 Go 1.27 的 profile 类型与参数形态，不把示例输出当作已在本机执行的运行证据。

先把“阻塞”与“泄漏”分开

普通 goroutine profile 可以告诉你哪些 goroutine 当前停在某个调用栈上；goroutineleak 则进一步尝试回答“它是否已经不可能被唤醒”。这需要运行时结合垃圾回收器追踪引用关系，因此它的结论更窄，但通常比按栈猜测更直接。

两种参数形态：profile 名称要写对

程序内读取时，profile 名称就是字符串 goroutineleak。服务已经导入 net/http/pprof 并注册处理器时，对应的 HTTP 路径也是同名 profile。两者表达的是同一类画像，差别只是采集入口。

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof" // 注册 pprof 路由，包括 goroutineleak。
    "runtime/pprof"
)

func main() {
    // 程序内查找时必须使用正式的 profile 名称。
    if p := pprof.Lookup("goroutineleak"); p == nil {
        log.Println("当前运行时没有 goroutineleak profile")
    } else {
        log.Println("goroutineleak profile 已可用")
    }

    // 仅示意服务入口；生产环境应把调试端口放在受控网络边界内。
    log.Fatal(http.ListenAndServe("127.0.0.1:6060", nil))
}

HTTP 采集地址是 /debug/pprof/goroutineleak，而不是普通的 /debug/pprof/goroutine。前者聚焦运行时判定的泄漏，后者是当前 goroutine 状态的常规画像；排查时可以按需要分别保存。

# 采集 goroutine 泄漏画像，文件交给 go tool pprof 分析。
curl http://127.0.0.1:6060/debug/pprof/goroutineleak > leak.prof

# 进入交互分析，按函数名定位阻塞位置。
go tool pprof leak.prof

上面的命令只说明参数形态：profile 名称和 URL 路径都必须是 goroutineleak。如果服务没有挂载 pprof HTTP 处理器，就使用程序内的 Lookup 结果写出 profile，不能把普通 goroutine 路径改名后当成同一 profile。

为什么全局引用会让画像漏掉阻塞

最容易误判的是“它永远不会再收到值，但 channel 还在全局变量里”。goroutineleak 的核心是可达性：如果阻塞 channel、锁或条件变量仍能从全局变量，或者从某个可运行 goroutine 的局部变量一路找到，运行时不能证明它已经没有唤醒可能，因此不会把它当成泄漏报告。

这不是说全局变量一定安全，而是说 profile 的证明标准更保守。把一个并发原语长期放进全局状态，会扩大运行时的可达范围；排查这类问题应回到所有权和生命周期，确认谁创建、谁关闭、谁最后一次使用，而不是只看 profile 是否出现。

四类常见未命中原因，按场景选择补充手段

把“画像没有发现”拆成下面四类，通常比反复调整采集次数更有效。

• 引用仍然可达：channel、Mutex、Cond 或 WaitGroup 仍被全局变量或可运行 goroutine 持有，运行时无法证明它永远无人使用。
• 阻塞类型不在范围内：文件读、网络读、直接系统调用以及没有使用上述原语实现的自定义自旋锁，不属于该 profile 的检测集合。
• 泄漏还没有发生：代码路径尚未走到真正的永久阻塞点，profile 不能预测一次将来可能发生的泄漏。
• 问题是业务等待而非永久泄漏：例如等待外部服务、等待定时器或等待下一批任务，当前停住不等于永远不会唤醒。

收尾：把它当成精确探测器，而不是全量扫描器

这篇标题里的“参数形态”有两个关键点：程序内参数是 pprof.Lookup("goroutineleak")，HTTP 参数对应 /debug/pprof/goroutineleak；但写对名字只解决采集入口，不会扩大检测范围。真正的边界来自运行时能否确认并发原语的不可达性。

如果画像为空，先问三个问题：阻塞是否发生在 channel 或 sync 原语上？阻塞原语是否还被全局或可运行 goroutine 引用？采集时问题是否已经实际发生？三个答案都指向“是、不可达、已发生”时，才适合期待 goroutineleak 给出定位。

两个容易混淆的问题

为什么看到很多阻塞 goroutine，却只有少数出现在 goroutineleak？ 因为普通阻塞包含 IO、暂时等待和仍有可达持有者的原语；goroutineleak 只保留运行时能够证明永久泄漏的子集。

只升级到 Go 1.27 就能发现旧版本所有泄漏吗？ 不能。Go 1.27 让该 profile 正式可用，但它仍受阻塞原语和可达性边界限制；升级后仍应结合普通画像、测试与业务生命周期排查。