Go 怎样把 pprof 挂到独立 ServeMux

我第一次把 Go 服务的业务路由从默认注册表迁到自定义 http.ServeMux 时，业务接口都能访问，/debug/pprof/ 却变成了 404。后来发现，问题不在 profile 没有生成，而在于 pprof 的默认注册位置和服务器实际使用的 mux 不是同一个对象。

解决方式很明确：如果服务使用独立的 ServeMux，就不要只依赖 import _ "net/http/pprof" 的副作用，而是用 pprof.Index、pprof.Handler(name)、pprof.Profile、pprof.Symbol 和 pprof.Trace 显式挂载到目标 mux。官方文档地址：https://pkg.go.dev/net/http/pprof。

pprof 默认服务的是 DefaultServeMux；自定义 mux 不会自动继承这些路由。要把诊断入口挂到独立 mux，关键是“取出 handler，再注册到目标 mux”，而不是重复导入包。

为什么默认写法换成自定义 mux 后会失效

我以前习惯这样启动诊断服务：

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof" // 只为触发 pprof 的默认路由注册
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/api/ping", func(w http.ResponseWriter, r *http.Request) {
        // 业务路由只挂到当前自定义 mux。
        w.WriteHeader(http.StatusNoContent)
    })

    // 传入自定义 mux 后，服务器不会去使用 DefaultServeMux。
    log.Fatal(http.ListenAndServe(":8080", mux))
}

匿名导入仍然会让 pprof 把默认入口注册到 http.DefaultServeMux，但最后传给 ListenAndServe 的是变量 mux。这两个 mux 是两个路由表，因此访问 /debug/pprof/ 时，业务服务器只会在自定义表里匹配。

官方的 ServeMux 定义可以简单理解为“请求路径到 handler 的匹配器”。服务器的 Handler 决定究竟查哪一张表；导入 pprof 并不会把 handler 同时复制到所有 mux。

先判断问题出在注册表还是 profile

排查时我会先把问题拆成两个判断：第一，目标服务器到底使用哪个 mux；第二，目标 mux 有没有对应的 pprof handler。只要第一步确认传入的是自定义 mux，就不应继续期待默认注册副作用自动生效。

可以用下面这张对照表快速定位：

这里的“profile 不存在”与“路由没有挂上”是两件事。pprof.Handler(name) 返回的是服务指定 profile 的 HTTP handler；它必须先进入实际被服务器使用的 mux，客户端才有机会请求到它。

把 pprof handler 显式挂到独立 ServeMux

我通常把注册动作集中在一个函数里，让路由表的完整性一眼可见。索引页、命令行信息、CPU profile、symbol、trace 和命名 profile 分开注册，后面替换路径前缀也比较容易。

package diagnose

import (
    "net/http"
    "net/http/pprof"
)

// MountPprof 把标准 pprof handler 挂到调用方提供的 mux。
func MountPprof(mux *http.ServeMux) {
    // 目录入口由 Index 负责列出可用 profile。
    mux.Handle("/debug/pprof/", http.HandlerFunc(pprof.Index))
    // 这些入口不是命名 profile，需要绑定对应的专用 handler。
    mux.Handle("/debug/pprof/cmdline", http.HandlerFunc(pprof.Cmdline))
    mux.Handle("/debug/pprof/profile", http.HandlerFunc(pprof.Profile))
    mux.Handle("/debug/pprof/symbol", http.HandlerFunc(pprof.Symbol))
    mux.Handle("/debug/pprof/trace", http.HandlerFunc(pprof.Trace))

    // Handler(name) 服务 runtime/pprof 中按名称登记的 profile。
    for _, name := range []string{
        "allocs", "block", "goroutine", "heap", "mutex", "threadcreate",
    } {
        path := "/debug/pprof/" + name
        mux.Handle(path, pprof.Handler(name))
    }
}

这个函数的重点不是把所有字符串集中起来，而是明确区分两类入口：Index、Profile、Symbol 等是包导出的专用函数；allocs、heap 等则通过 Handler(name) 按 profile 名称取得。

如果你的 mux 注册方式还没有启用方法和主机匹配，保持路径写法与目标 Go 版本的 ServeMux 规则一致即可。本文只讨论 handler 到 mux 的归属，不把版本差异扩大成另一套路由教程。

把诊断 mux 绑定到独立 HTTP Server

如果目标是避免诊断路由混进业务入口，我更倾向于创建两个 mux，再让两个 http.Server 各自持有一个 Handler。这样从代码结构上就能看出：业务请求不会因为共享路由表而意外暴露诊断入口，诊断入口也不会覆盖业务路径。

package main

import (
    "log"
    "net/http"

    "example.com/project/diagnose"
)

func main() {
    businessMux := http.NewServeMux()
    businessMux.HandleFunc("/api/ping", func(w http.ResponseWriter, r *http.Request) {
        // 业务 mux 只声明业务接口，避免把诊断入口带到公共端口。
        w.WriteHeader(http.StatusNoContent)
    })

    debugMux := http.NewServeMux()
    diagnose.MountPprof(debugMux)

    debugServer := &http.Server{
        Addr:    "127.0.0.1:6060",
        Handler: debugMux, // 独立服务器只接收诊断 mux。
    }
    go func() {
        // 启动错误必须被记录，避免诊断端口没有监听却无人知晓。
        log.Printf("pprof server: %v", debugServer.ListenAndServe())
    }()

    // 业务端口使用另一张 mux，两个路由表彼此独立。
    log.Fatal(http.ListenAndServe(":8080", businessMux))
}

这种拆分的收益是边界清楚，不是“性能更高”。Handler 只是告诉服务器请求交给哪张 mux；真正的访问隔离仍然取决于监听地址、网络策略和部署配置。将诊断端口绑定到回环地址只是示例中的一个边界选择，是否适合生产环境要结合实际采集方式决定。

按请求路径复查挂载结果

文章不需要靠运行截图证明结构，但在实际项目中，复查应该围绕路由归属进行。先看 http.Server.Handler 是不是目标 mux，再逐项对照注册表：

• /debug/pprof/ 是否绑定了 pprof.Index，索引页是否属于诊断 mux。
• /debug/pprof/heap、/debug/pprof/goroutine 等命名 profile 是否调用了 pprof.Handler(name)。
• /debug/pprof/profile、/debug/pprof/symbol、/debug/pprof/trace 是否分别注册。
• 业务 http.Server 是否仍然使用自己的 mux，而不是无意间改回 DefaultServeMux。

还有一个容易忽略的点：如果你把 pprof 路径改成了自定义前缀，所有图示、文档和采集命令都要同时更新。不要只改索引页路径，却让 profile handler 仍然落在旧前缀下。

这套写法适合哪些场景

当业务服务已经采用自定义 mux、需要把诊断入口放在独立端口，或者希望把 pprof 注册动作封装进一个可复用模块时，显式 handler 是更稳妥的选择。它的代价是多写几行注册代码，也需要随着 Go 标准库入口变化维护清单。

如果只是临时本地调试，而且服务本来就使用 DefaultServeMux，匿名导入配合默认服务器仍然简单。但只要应用明确传入了自定义 ServeMux，就应该把“默认注册到哪里”和“服务器实际使用哪张表”先对齐，再决定是否拆分端口。

相关问题

只调用 pprof.Handler("heap") 能打开索引页吗？

不能。它只返回指定 profile 的 handler；索引页还需要单独绑定 pprof.Index。

必须使用独立端口才能挂到独立 ServeMux 吗？

不必须。可以把 pprof handler 注册到与业务相同的 mux，也可以使用独立 mux 和独立服务器；端口拆分是访问边界选择，不是 handler 注册的前提。

为什么匿名导入 pprof 后，自定义 mux 仍然没有路由？

匿名导入触发的是默认注册表的初始化。自定义 mux 是另一张路由表，不会自动复制 DefaultServeMux 中的条目。

总结

这次问题最后可以归结为一个对象关系：pprof 提供 handler，ServeMux 保存路由，HTTP Server 决定使用哪张 ServeMux。把这三层关系写在代码里，独立挂载就不再依赖隐式副作用。