pprof 是需配合运行时状态、采样策略和可视化路径使用的诊断工具链，非一键开关；常见问题包括未启用采样、HTTP路由未注册、无有效CPU负载、混淆allocs与heap指标、符号表缺失等。
pprof 不是“开了就能看到瓶颈”的开关，而是需要配合运行时状态、采样策略和可视化路径一起用的诊断工具链。直接跑 go tool pprof 却看不到火焰图或 CPU 占比，大概率是没启用采样或服务没跑够时间。
pprof HTTP 接口没响应？检查 net/http/pprof 是否已注册
Go 标准库的 net/http/pprof 包不会自动挂载路由，必须显式导入并注册——很多人写了 import _ "net/http/pprof" 就以为万事大吉，但没调用 http.DefaultServeMux 或没启动 HTTP server，接口根本不存在。
- 确保在
main()或服务初始化阶段调用了http.ListenAndServe(":6060", nil)（或传入自定义 mux） - 导入语句必须带下划线：
import _ "net/http/pprof"，否则包 init 函数不执行 - 若用了 Gin/Echo 等框架，不能只靠下划线导入，需手动把
/debug/pprof/路由注册到对应 router 上（例如 Gin 中用r.GET("/debug/pprof/*pprof", gin.WrapH(http.DefaultServeMux))） - 访问
http://localhost:6060/debug/pprof/应返回 HTML 页面；如果 404，说明路由未生效
CPU profile 采样不到数据？确认程序有持续计算负载
runtime/pprof.StartCPUProfile 和 HTTP 接口的 /debug/pprof/profile 都依赖 OS 信号（如 SIGPROF）做定时采样，默认 100Hz。如果程序大部分时间在阻塞（如 sleep、channel receive、syscall 等待），CPU profile 就几乎全是空样本。
- 测试时避免写
time.Sleep(10 * time.Second)后就退出——要保证采样期间有真实 CPU 活动（比如循环计算、JSON 解析、map 遍历等） - HTTP 方式采集建议加
?seconds=30参数（如curl -o cpu.pb.gz "http://localhost:6060/debug/pprof/profile?seconds=30"），确保采样窗口足够长 - 本地调试可用
pprof -http :8080 cpu.pb.gz查看火焰图；若火焰图扁平或只有 runtime.goexit，基本就是没跑起来有效负载
内存 profile 显示 allocs 但 not in use？区分 allocs vs heap
/debug/pprof/allocs 统计所有堆分配动作（含已释放对象），/debug/pprof/heap 默认只抓 live objects（即当前仍在引用的对象）。新手常误以为 “allocs 高 = 内存泄漏”，其实只是分配频繁；真正要看泄漏，得盯 heap 的 inuse_objects/inuse_space 增长趋势。
立即学习“go语言免费学习笔记（深入）”；
- 采集 heap 数据前，先触发 GC：
curl "http://localhost:6060/debug/pprof/heap?gc=1"，避免缓存干扰 - 对比两次
heap快照：启动后立刻抓一次，压测几分钟后再抓一次，用pprof -base base.pb.gz new.pb.gz看增量 - 注意
inuse_space是当前存活对象总字节数，alloc_space是历史总分配量——后者高但前者稳定，通常只是短生命周期对象多，未必有问题
火焰图函数名显示 unknown 或 runtime.xxx？符号表缺失或内联干扰
Go 编译默认开启内联（-gcflags="-l" 可关），导致小函数被折叠，pprof 里只显示调用方；另外，strip 了 debug symbol 的二进制（如用 go build -ldflags="-s -w"）会让函数名变成 unknown 或地址形式。
- 调试阶段禁用内联：
go build -gcflags="-l" -o server server.go，让调用栈更完整 - 保留符号表：去掉
-s（strip symbols）和-w（omit DWARF），至少留一个（推荐留 DWARF：-ldflags="-w"可去符号但保调试信息） - 使用
pprof -symbolize=executable强制从二进制还原符号；若仍显示runtime.mcall这类底层函数，说明热点真在调度/锁竞争上，需结合/debug/pprof/goroutine或/debug/pprof/block进一步查
pprof 的价值不在“一键出图”，而在你能读懂图里每个节点的上下文含义——比如 runtime.scanobject 高，不是代码问题，是 GC 压力大；net.(*netFD).Read 占比突增，可能意味着连接数暴涨或读缓冲区太小。别跳过采样逻辑和指标语义，直接套结论。
