排查 goroutine 泄漏,关键不在某个瞬间的 goroutine 总数偏高,而在“数量是否随时间或请求量单调上升,且堆积集中在同一批调用栈”。先把这个信号确认下来,再去看阻塞点,比直接翻代码有效得多。
适用于常驻 HTTP/RPC 服务、常驻消费者和长期运行的定时任务。做法是:启动稳定后记录一次基线,按固定间隔采样 goroutine 数量与阻塞栈,对比同一调用栈的堆叠数量是否持续增长。验证方式是修复后回放同一路径,观察数量能回落到基线且不再随时间爬升。边界:后台常驻 goroutine、GC 相关协程、阻塞在系统调用的协程都会计入总数,不能只看总量下结论;短生命周期进程和一次性脚本不适用这套判断。
先确认当前场景和目标
先确认四件事,否则很容易把正常波动当成泄漏。第一,进程是常驻还是短任务——短任务随请求结束就退出,谈不上泄漏。第二,有没有基线:服务启动并跑完预热后,稳定状态下的 goroutine 数量大概是多少,这个数值要在同版本、同配置、同机器规格下取。第三,增长形态:是随请求量线性增长,还是随时间匀速增长,前者多半和请求处理路径有关,后者常见于 Ticker、后台循环、重连逻辑。第四,伴随现象:内存是否同步上涨、是否有大量连接未关闭、是否出现响应变慢但 CPU 不高。
可以用下面这段最小代码先把数量暴露出来,挂到健康检查或监控里,作为后续对比的基准。
import (
"net/http"
"runtime"
)
func init() {
http.HandleFunc("/debug/goroutines", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte(strconv.Itoa(runtime.NumGoroutine())))
})
}判断条件可以写成清单:数量在无流量时是否仍缓慢上升;重启后多久回到基线;增长是否可复现;是否集中出现在某类请求、某个下游超时之后。只要其中两条成立,就值得按下面的顺序继续查。

按这个顺序处理
- 抓阻塞栈,而不是猜代码。如果服务已经引入 net/http/pprof,直接取
/debug/pprof/goroutine?debug=2,它给出每个 goroutine 的完整调用栈,是定位泄漏最直接的材料。没有 pprof 时,可以对进程发 SIGQUIT 拿到全量栈,或在代码里runtime.Stack(buf, true)打到日志。 - 按调用栈聚合数量。把 debug=2 的输出按栈顶几行分组统计,数量最多的那组通常就是泄漏点。用 pprof 更方便:
go tool pprof http://host:port/debug/pprof/goroutine,在交互里用top看聚合、traces看完整路径。间隔一段时间抓两次做 diff,只在两份里都出现且数量上涨的栈才是嫌疑对象。 - 按阻塞原因分类。栈里常见的状态词能直接指向问题类型:
chan receive/chan send指向无人收发的通道;select指向缺少退出分支的等待;semacquire指向锁竞争或信号量未释放;IO wait多为连接或文件未关闭;sync.runtime_Semacquire结合 WaitGroup 未 Done 也常见。 - 回到代码对照常见成因。无缓冲 channel 的发送方没有对应接收方;context 已超时但 goroutine 仍在往 channel 写结果且没有 select 退出分支;for 循环里无节制地
go func(),没有并发上限;HTTP 客户端未读 body、未 close resp.Body;time.NewTicker未 Stop;自定义连接池取用后未归还。对着可疑栈往上翻三层,基本能落到具体函数。 - 把检查固化进测试。用 goleak 一类工具在单元测试结束时断言无遗留 goroutine,或手写一个“执行前后 NumGoroutine 差值”的断言,配合
go test -race一起跑,让同类问题在合入前暴露。
处理手段上,优先补退出路径:给每个派生的 goroutine 绑定 context,在 select 里加 case <-ctx.Done();给阻塞发送加带缓冲通道或 default 分支;给并发起 goroutine 的地方加信号量或 worker pool 限制;确保 defer 里关闭 ticker、连接、响应体。这些是修复,不是把问题藏起来。
改完后怎么验证
验证要看“同一路径回放后是否还堆积”,而不是看单次重启后数值变低。具体动作:用与泄漏时相同的请求量或相同的超时场景回放一轮,在开始、结束、结束后若干分钟各采一次 goroutine 数量与阻塞栈;对比修复前后的 pprof diff,确认原先数量最多的那组栈已消失或数量不再增长。预期信号是:结束回放后数量能回落到启动基线附近,且在没有流量时保持平稳,不再随时间爬升。
同时观察内存和连接数是否同步稳定下来,避免只修了 goroutine 而资源仍在泄漏。如果条件允许,把这次采样的对比结果和可疑栈摘要附在变更说明里,后续同类问题可以直接比对。
容易忽略的边界
- pprof 没注册或端口未对外暴露时,从外部取不到栈;内网服务需要走本地端口转发或临时在管理端口挂载,操作前确认权限与暴露范围,用完及时撤掉。
debug=1是聚合视图,适合看数量分布;debug=2是完整栈,适合定位。只看聚合数容易把不同原因的协程加在一起,判断会失真。- 不同 Go 版本的 runtime 内部常驻协程数量可能不同,基线必须在同版本、同 GOMAXPROCS 配置下建立,跨版本比数值没有意义。
- 阻塞在系统调用或网络读写上的 goroutine 属于业务常态,不必然是泄漏;判断依据是数量是否单调增长,而不是是否处于等待状态。
- goleak 之类工具对包含长期后台协程的包需要配置忽略规则,否则会误报,测试里应显式声明允许存在的常驻协程。
- 如果一时无法定位,重启或扩副本只能暂时压住现象,不能替代修复;这类动作建议明确标注为临时处置,并保留采样证据继续跟进。