Go goroutineleak 采样为空时应该先排查什么

如果 Go 的 goroutineleak 采样为空，第一反应不应该是“pprof 没采到 goroutine”，而是先确认 profile 名称、Go 版本、阻塞条件和输出参数。这个 profile 只报告运行时判定为“无法再被唤醒”的泄漏 goroutine；普通的等待、短暂的锁竞争和仍可能恢复的阻塞，都可能得到空结果。

最先排查四件事：是否使用 Go 1.27 或正确启用实验版本；是否请求了 goroutineleak 而不是 goroutine；被阻塞的并发原语是否已经对其他可运行 goroutine 不可达；是否把 debug>=2 的全量栈输出误当成泄漏数量。

官方地址：https://go.dev/doc/go1.27

标准库文档：https://pkg.go.dev/runtime/pprof

先确认 goroutineleak 真的可用

goroutineleak 是 Go 1.27 正式提供的预定义 profile，名称就在 runtime/pprof 的内置 profile 表中。Go 1.26 时它仍属于实验能力，需要使用对应的构建实验开关；如果程序实际由更旧的工具链编译，pprof.Lookup("goroutineleak") 返回空指针是版本问题，不是采样结果为空。

先把“profile 不存在”和“profile 存在但当前没有泄漏”分开。下面的函数只负责读取 profile，不把 Count() 当作最终结论，因为泄漏检测发生在写出 profile 时触发的检测 GC 中。

package main

import (
    "errors"
    "io"
    "runtime/pprof"
)

func writeLeakProfile(w io.Writer, debug int) error {
    // 预定义 profile 在 Go 1.27 中可直接按名称取得。
    profile := pprof.Lookup("goroutineleak")
    if profile == nil {
        // nil 表示当前构建没有这个 profile，先查工具链或实验开关。
        return errors.New("goroutineleak profile is unavailable")
    }
    // debug=0 适合 pprof 数据，debug=1 适合阅读文本；两者都会筛选泄漏 goroutine。
    return profile.WriteTo(w, debug)
}

如果这里得到的是“profile 不存在”，先执行 go version，再检查服务实际使用的构建镜像、CI 工具链和运行二进制，而不是继续调整 goroutine 业务代码。

空结果的核心：阻塞不等于泄漏

Go 运行时并不是看到某个 goroutine 处于等待状态就把它记为泄漏。官方定义的检测对象是：goroutine 被 channel、sync.Mutex、sync.Cond 等并发原语阻塞，并且从仍可运行的 goroutine 出发，已经找不到让这个原语恢复可达的路径。

因此下面几类情况会自然得到空采样：

检查 goroutine 是否有完整的唤醒路径

排查采样为空时，应该反向阅读 goroutine 的生成点：它在正常分支、错误分支、超时分支和取消分支上是否都能退出？特别是“父 goroutine 提前返回、子 goroutine 继续向无缓冲 channel 发送”的组合，确实可能构成泄漏，但只有当 channel 同时对其他运行中 goroutine 不可达时，运行时才有机会把它报告出来。

func startWorker(ctx context.Context, out chan

这段代码的重点不是让每次采样都出现记录，而是明确生命周期契约：谁创建 goroutine，谁负责取消；谁创建 channel，谁决定关闭；错误返回后，剩余发送者是否仍有可完成的通信。如果这些路径完整，goroutineleak 为空反而是符合预期的。

分别检查 Lookup 和 HTTP 入口

标准库提供两类入口。进程内可以通过 pprof.Lookup("goroutineleak") 写出 profile；引入 net/http/pprof 后，则可以从 /debug/pprof/goroutineleak 请求。两者的 profile 名称必须完全是小写的 goroutineleak，不能写成 goroutine-leak，也不要把普通的 /debug/pprof/goroutine 当成同一项。

# 读取经过符号化的泄漏文本；地址与端口按实际服务配置替换
curl -sS 'http://127.0.0.1:6060/debug/pprof/goroutineleak?debug=1' \
  -o goroutineleak.txt

# 读取全部 goroutine 栈，用来对照“总量”和泄漏 profile 的差异
curl -sS 'http://127.0.0.1:6060/debug/pprof/goroutineleak?debug=2' \
  -o goroutine-stacks.txt

HTTP 入口在请求时执行带泄漏检测的 GC，然后根据 debug 参数选择输出。服务没有挂载 pprof、路径被反向代理改写，或请求落到了另一份旧二进制，都会造成“看起来为空”的错觉；这时应先确认入口对应的进程和路由。

不要把 debug=2 当成泄漏 profile

这是最容易误判的一点。debug=0 输出 pprof 的压缩协议数据，debug=1 输出适合人读的文本；这两个级别都按泄漏集合筛选。对于这个预定义 profile，debug>=2 会走普通 goroutine 栈输出，并把非泄漏 goroutine 也包含进去。

所以排查顺序可以固定为：先用 debug=1 看泄漏文本；需要和全量栈对照时，再单独请求 debug=2。如果只请求了 debug=2，看到很多 goroutine 并不能证明泄漏；如果 debug=1 为空，也不能据此断定没有任何 goroutine 处于阻塞状态。

把空采样转换成可执行的检查清单

1. 确认构建与运行时：Go 版本、实际二进制和部署镜像是否一致，Lookup("goroutineleak") 是否为 nil。
2. 确认 profile 名称：使用 goroutineleak，不要把普通 goroutine profile、block profile 或第三方工具名称混在一起。
3. 确认采样入口：进程内写出与 HTTP endpoint 是否指向同一进程，反向代理是否改写了路径。
4. 确认 debug 级别：用 debug=1 判断泄漏集合，用 debug=2 只做全量栈对照。
5. 确认生命周期：沿着 channel、锁和条件变量回看创建者、唤醒者、关闭者与取消者，找出所有提前返回路径。

如果最后仍为空，结论应写成“当前检测模型没有识别出可证明的泄漏”，而不是“程序绝对没有 goroutine 泄漏”。官方也明确说明，基于可达性的检测无法覆盖所有永久阻塞情形，尤其是并发原语仍被全局变量或可运行 goroutine 的局部变量持有时。

常见问题

goroutineleak 和 goroutine profile 有什么区别？

goroutine 报告当前所有 goroutine 的栈；goroutineleak 只报告运行时判定为泄漏的集合。前者适合看总量和状态，后者适合缩小到疑似永久阻塞点。

为什么 goroutine 数量很多但 goroutineleak 为空？

数量多只说明当前存在很多 goroutine，不说明它们都无法被唤醒。只要它们仍有可达的通信、锁释放或取消路径，就可能不进入泄漏集合。

debug=2 为空是不是检测失败？

不能这样判断。debug=2 的语义是输出全部 goroutine 栈；应先用 debug=1 看泄漏筛选结果，再用 debug=2 做上下文对照。

应该反复请求直到出现记录吗？

不应该。每次写出都会触发泄漏检测 GC；重复请求不会把一个仍可恢复的阻塞强行变成泄漏。更有价值的是回到 goroutine 的唤醒契约，检查错误、超时和取消分支。

总的来说，Go goroutineleak 采样为空时，先排查版本和名称，再排查阻塞原语的可达性，最后核对 HTTP 入口与 debug 分支。空结果代表当前检测模型没有找到可证明的泄漏，不代表可以跳过 goroutine 生命周期设计。