goroutine泄漏如何用新剖面定位

如果 Go 服务里的 goroutine 数量持续上涨，先不要把“数量多”直接等同于“泄漏”。普通 goroutine 剖面只能告诉你当前有哪些协程和调用栈；从 Go 1.27 开始，新的 goroutineleak 剖面可以专门报告一类已经不可能解除阻塞的协程，定位效率会更高。

实战上可以先看 runtime.NumGoroutine 的趋势，再通过 net/http/pprof 暴露剖面，最后用 go tool pprof 查看 goroutineleak 样本落在哪个 channel 或 sync 原语上。

一句话结论：普通 goroutine 剖面回答“现在谁在阻塞”，goroutineleak 剖面回答“哪些阻塞已经没有解除路径”；先用前者观察趋势，再用后者缩小泄漏边界。

先用数量趋势确认问题值得剖析

goroutine 数量上涨只是信号，不是结论。高流量时，等待连接、排队任务或定时器都可能让协程暂时变多；真正可疑的是请求量回落后数量仍不回落，或者同一类调用栈持续累积。

可以在服务自己的指标采集处记录数量。这个示例只负责暴露一个趋势值，不在采集函数里启动额外协程，也不把单次采样当成泄漏判定。

package main

import (
	"expvar"
	"runtime"
)

func init() {
	expvar.Publish("goroutines", expvar.Func(func() any {
		// 只读取运行时当前数量，交给指标系统做时间序列观察。
		return runtime.NumGoroutine()
	}))
}

观察时至少把 goroutine 数量和请求量、队列长度、实例重启时间放在一起看。若请求已经恢复平稳，但数量仍呈阶梯式上升，就值得继续采集剖面；如果只是流量高峰期间同步上升、峰后回落，通常不能仅凭这个指标判定泄漏。

普通 goroutine 和 goroutineleak 有什么区别

普通 goroutine 剖面包含当前协程的栈信息，适合回答“哪些函数在等待 channel、锁、网络或文件”。它不自动区分暂时等待和永久泄漏，所以样本数量大时仍需要人工结合生命周期判断。

goroutineleak 是 Go 1.27 新增的 profile 类型。运行时会利用垃圾回收阶段的可达性关系，筛出被 channel 或 sync.Mutex、sync.RWMutex、sync.WaitGroup、sync.Cond 等并发原语永久阻塞的协程。它的优势是缩小候选，边界是不能覆盖所有阻塞原因。

因此两种剖面不是互相替代：普通剖面可以帮助你发现网络 IO、文件 IO 等更广泛的等待；新剖面则更适合把永久阻塞候选直接聚焦到 Go 原生并发原语。

通过 net/http/pprof 暴露新剖面

如果服务已经接入 net/http/pprof 的默认处理器，Go 1.27 会自动提供 /debug/pprof/goroutineleak。下面只展示一个最小的本地服务入口，生产环境应把调试端口放在受控网络边界内，并按现有运维策略做访问限制。

package main

import (
	"log"
	"net/http"
	_ "net/http/pprof" // 注册 /debug/pprof/ 及其 profile 处理器。
)

func main() {
	server := &http.Server{Addr: "127.0.0.1:6060"}
	log.Printf("pprof listening on %s", server.Addr)
	if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		log.Fatal(err) // 启动失败要立即暴露，避免以为 profile 已经可用。
	}
}

如果应用使用自定义 ServeMux，不能只导入包就假定所有路由都已经注册；应按 net/http/pprof 文档把处理器挂到自己的管理 mux 上。本文示例使用默认 mux，只为了说明 profile 名称和采集路径。

采集剖面并交给 go tool pprof

可以先分别采集普通 goroutine 和新剖面。命令中的 URL 是 pprof 监听地址，不是文章链接；把结果保存为文件后，再交给本地工具分析。

# 保存全部当前 goroutine 栈，便于观察更广的等待类型。
curl -o goroutine.prof http://127.0.0.1:6060/debug/pprof/goroutine

# 保存 Go 1.27 的永久阻塞候选剖面。
curl -o goroutineleak.prof http://127.0.0.1:6060/debug/pprof/goroutineleak

# 打开新剖面，后续可用 top、list 等命令定位函数。
go tool pprof goroutineleak.prof

进入 pprof 交互界面后，先用 top 看样本集中在哪些函数，再用 list 函数名 回到源码行。重点不是把 Total 当作压测结果，而是看样本栈是否反复落在发送、接收、加锁或等待计数器的位置。

Type: goroutineleak
(pprof) top
(pprof) list processWorkItems
(pprof) quit

如果服务开启了 pprof 但新端点不存在，先确认实际编译工具链和运行版本；goroutineleak 不是旧版 Go 中普通 goroutine profile 的别名，不能通过改 URL 拼出能力。

从阻塞代码行回到泄漏原因

新剖面给出的通常是“某个协程永久卡在某个原语上”，修复仍要回到业务生命周期。最常见的模式是：父流程提前返回，子协程仍向无缓冲 channel 发送；或者取消分支结束了接收方，却没有给发送方留下退出路径。

func runOnce(ctx context.Context) error {
	resultCh := make(chan result)

	go func() {
		value := doWork()
		select {
		case resultCh 

上面的关键不是“所有 channel 都要加 buffer”，而是让生产者和消费者共享明确的结束条件。若业务允许结果只交付一次，也可以使用容量为 1 的 channel；若有多个 worker，则应由负责发送的一方关闭 channel，并让接收循环能在关闭后退出。

sync.WaitGroup 的问题则常见于计数没有归零，例如在循环中错误地等待，导致后续任务永远没有机会完成。用 list 定位到 Wait 后，要反查 Add、Done 的成对关系，而不是只在等待行外层加超时。

新剖面的覆盖范围和排查边界

goroutineleak 不是“所有泄漏检测器”。它主要识别被 Go 原生 channel 或部分 sync 原语永久阻塞的协程；网络 IO、文件 IO、系统调用、自定义自旋锁等等待，不能因为没有出现在新剖面里就断言没有问题。

建议按下面的顺序组合工具：

最后再检查修复后的数量趋势是否恢复，以及同一调用栈是否不再积累。这个闭环比单次看到“Total 较大”更可靠：剖面负责缩小范围，代码审查负责确认生命周期，趋势负责观察修复是否真正生效。

常见问题

goroutine 数量高就是泄漏吗？

不是。高并发、连接等待和正常后台任务都可能使数量暂时升高，应结合流量和时间趋势判断。

goroutineleak 能替代普通 goroutine 剖面吗？

不能。新剖面覆盖范围更窄，普通剖面仍适合查看网络 IO、文件 IO 和所有当前栈。

为什么 profile 里没有我的泄漏？

可能是阻塞原因不属于支持的 channel 或 sync 原语，也可能是泄漏尚未发生或原语仍被可运行协程持有；应回到普通剖面和生命周期代码一起排查。