Gin 中 pprof 注册失败因未将 net/http/pprof handler 挂载到 Gin router，需用 gin.WrapH 或 gin-contrib/pprof.Register；heap 采集失败常因 GC 未触发，应加 -seconds=30 或主动分配内存。
pprof 在 Gin 中注册失败导致 /debug/pprof/heap 返回 404
不是端口没开、也不是路由写错，net/http/pprof 的 handler 根本没挂到 Gin 的 router 上。Gin 不用默认 http.ServeMux，所以 import _ "net/http/pprof" 这句对它完全无效。
常见错误包括：
- 直接调用
pprof.Index等函数但没用gin.WrapF或gin.WrapH包装 - 用了
github.com/gin-contrib/pprof却忘记调用pprof.Register(r) - 自己手写 group 路由时漏掉了
/debug/pprof/heap对应的pprof.Handler("heap")
最简验证方式：curl -v http://localhost:8080/debug/pprof/。返回 HTML 页面才算生效；若返回 404，说明路径未暴露。推荐用官方 contrib 包：先 go get github.com/gin-contrib/pprof，再在路由初始化处加 pprof.Register(engine)。
go tool pprof 抓不到 heap 数据或卡住
执行 go tool pprof http://localhost:8080/debug/pprof/heap 卡住或报 context deadline exceeded，大概率不是网络问题，而是程序当前没分配内存、GC 没触发，导致 inuse_space 几乎为 0，pprof 等几秒就放弃。
立即学习“go语言免费学习笔记（深入）”；
关键点：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- Go 1.21+ 默认
GOGC=100，堆增长一倍才触发 GC；短逻辑、小分配下 GC 可能压根不发生 -
/debug/pprof/heap默认只返回存活对象（inuse_space），刚启动或低负载时天然为空 - 加
-seconds=30强制采集窗口期：go tool pprof -seconds=30 http://localhost:8080/debug/pprof/heap - 更可靠做法：先让服务持续分配（比如开 goroutine 循环
make([]byte, 1），再采集
用 runtime.ReadMemStats 判断是否真泄漏，别信 top 的 RSS
看到 top 里 RSS 到了 1.2GB，但 runtime.ReadMemStats(&ms) 显示 ms.HeapAlloc 才 15MB？那基本不是泄漏——空闲内存还在 HeapIdle 里，Go runtime 暂时没还给 OS，属正常行为。
真正要盯的是：
-
HeapAlloc是否在每次 GC 后稳定回落；若空闲期仍持续抬高（如 12MB → 14MB → 17MB），大概率有强引用未释放（比如全局map[string]*BigStruct忘了delete） - 每次调用
runtime.ReadMemStats必须传新变量，复用同一个runtime.MemStats实例会导致字段被覆盖污染 - 高频采样建议每秒 1–5 次，配合
debug.GC()主动触发后对比，比等自动 GC 更可控
Gin 项目中 goroutine 泄漏常被误认为内存泄漏
内存“涨得慢但停不住”，第一反应不该是翻 pprof/heap，而是看 runtime.NumGoroutine()：单次请求结束后数量不回落、压测后 30 秒仍居高不下、运行几小时单调上升——这八成是 goroutine 卡住了，间接钉住大对象。
确认方式：
- 访问
http://localhost:8080/debug/pprof/goroutine?debug=2（注意必须是?debug=2，?debug=1只给统计摘要） - 重点找卡在
chan receive、select、net.Conn.Read的堆栈，阻塞时间显示为数万秒级（如432000s）基本就是泄漏 - Go 1.24+ 可启用
GODEBUG=goleak=1，再访问/debug/pprof/goroutineleak?debug=1，返回带_Gleaked状态的即为确认项
协程泄漏不会 panic，但会悄悄拖垮内存——它比纯内存泄漏更隐蔽，也更常出现在 Gin 的中间件、超时控制、后台 ticker 等场景里。
