Go pprof.Lookup 如何导出指定名称的运行时剖面

你要导出指定名称的Go运行时剖面，直接调用标准库`runtime/pprof`中的`pprof.Lookup`方法传入对应剖面名称，拿到对应的Profile实例后，调用实例的`WriteTo`接口就可以把剖面数据导出到指定的文件或输出流中。

只要传入的剖面名是Go运行时预先注册的合法剖面类型，就能通过pprof.Lookup直接拿到对应实例完成导出，不需要额外引入第三方依赖。

要按名称导出 Go 的运行时剖面，直接调用 pprof.Lookup(name)，拿到非 nil 的 *pprof.Profile 后再调用 WriteTo。例如 pprof.Lookup("heap") 得到堆剖面，WriteTo(file, 0) 写出的就是可交给 go tool pprof 的压缩剖面文件。

Go pprof.Lookup 的最小导出写法

下面的函数把“按名称查找”和“落盘”拆开，调用方只需要传入剖面名称和目标文件名。示例使用标准库预定义的 heap，换成 goroutine、allocs 或其他已注册名称时，导出流程不变。

package main

import (
    "fmt"
    "os"
    "runtime/pprof"
)

func exportProfile(name, filename string) error {
    // Lookup 找不到名称时返回 nil，先判断可以避免空指针调用 WriteTo。
    profile := pprof.Lookup(name)
    if profile == nil {
        return fmt.Errorf("profile %q not found", name)
    }

    // 创建目标文件；defer 保证正常返回和写入失败路径都会尝试关闭文件。
    file, err := os.Create(filename)
    if err != nil {
        return fmt.Errorf("create profile file: %w", err)
    }
    defer func() {
        // 示例函数以 WriteTo 错误为主；生产代码可把 Close 错误纳入返回值。
        _ = file.Close()
    }()

    // debug=0 写出 pprof 工具使用的压缩协议数据。
    if err := profile.WriteTo(file, 0); err != nil {
        return fmt.Errorf("write profile %q: %w", name, err)
    }
    return nil
}

func main() {
    // 运行时剖面名称要和注册名称完全一致。
    if err := exportProfile("heap", "output.prof"); err != nil {
        fmt.Println(err)
    }
}

这里最容易漏掉的是 nil 判断。Lookup 不会因为名称拼错自动创建剖面，也不会把名称模糊匹配到相近项目。文件名只是输出位置，真正决定导出内容的是 name。如果要导出自定义剖面，应先用 pprof.NewProfile("your/name") 注册，再用同一个名称查找；同名重复注册会触发 panic，所以注册动作应放在明确的初始化路径中。

debug 参数决定文件给谁读取

WriteTo 的第二个参数不是“详细程度”这么简单，它决定输出格式。常用取值可以这样记：

生产采集通常选择 debug=0，因为它保留了工具需要的结构。若把 debug=1 的文本文件直接改名为 .prof，并不能把它变回标准压缩剖面；文本只是另一种输出表示。

导出后怎么确认文件确实可用

导出函数返回 nil 只说明写入过程没有报告错误，下一步还应把文件交给 pprof 工具读取。最小核对命令如下：

# 用 top 查看采样汇总，不打开交互式网页。
go tool pprof -top output.prof

# 需要图形界面时，再启动本地 HTTP 查看器。
go tool pprof -http=:0 output.prof

如果工具提示文件格式不对，先检查调用时是否真的使用了 debug=0，再确认目标文件不是空文件、是否被其他流程截断。若名称不存在，优先回到 Lookup 的返回值和注册路径排查，不要用修改扩展名的方式“修复”文件。

几个会影响结论的边界

第一，运行时剖面反映的是采样或累计统计，不是每一条执行记录；短时间、低负载任务得到的结果可能很稀疏。第二，heap 与 allocs 关注的指标不同，不能只看函数名就互换结论。第三，导出期间仍应把文件写入稳定位置，避免多个协程同时覆盖同一个文件名；如果服务支持并发诊断，建议用时间戳或请求 ID 生成独立文件名。第四，文件关闭错误也可能意味着落盘未完整，正式工具可用命名返回值接住 Close 错误，而不是长期忽略。

常见问题

pprof.Lookup 返回 nil，是否需要自己 new 一个 Profile？

只有在确实要记录自定义栈时才创建新的 Profile。预定义剖面名称写错时，应该先修正名称或确认注册时机，不要用空的新剖面掩盖配置问题。

导出 heap 前一定要手动调用 runtime.GC 吗？

不一定。是否在采集前触发 GC 取决于你要观察实时存活对象还是包含尚未回收对象的分配情况；改变采集前条件会改变结果，应该在实验说明里记录。

为什么生成了 output.prof，却打不开？

最常见原因是写入失败被忽略、使用了文本模式、文件为空，或导出过程被中断。保留 WriteTo 的返回错误，并用 go tool pprof -top 做一次格式核对。

直接使用 net/http/pprof 还需要 Lookup 吗？

HTTP 入口适合远程或临时抓取预定义剖面；需要在代码中选择名称、生成固定文件、保存自定义 Profile 时，直接使用 Lookup 和 WriteTo 更可控。