Go panic 时打印完整的调用栈

FreeGuideOnline 最新 2026-07-06

理解 Go 的 panic 和默认栈信息

Go 程序在发生运行时错误或主动调用 panic 后会立即停止执行，并输出当前 goroutine 的调用栈信息。默认情况下，这些信息会打印到标准错误输出，但往往只包含触发 panic 的 goroutine 的栈帧，而且可能因为缓冲问题而截断或不完整。

默认行为：当发生 panic 未恢复时，Go runtime 会打印类似 panic: runtime error: ... 的消息，以及 goroutine 的栈信息。但该栈信息只来自发生 panic 的那一个 goroutine。
为什么需要完整调用栈：在多 goroutine 程序中，问题可能由其他 goroutine 的状态引起。调试时如果能拿到所有 goroutine 的完整栈信息，可以极大降低排查难度。
典型场景：程序意外崩溃、复杂并发死锁、资源泄漏的偶发 panic 等。

核心思路：使用 `debug.Stack()` 获取完整栈

Go 标准库 runtime/debug 提供了 debug.Stack() 函数，它能返回当前 goroutine 的调用栈字节切片，并且不受 panic 截断影响。配合 recover，我们可以在捕获 panic 时主动打印这份完整信息。

注意：debug.Stack() 返回的是当前 goroutine 的完整栈。若要获取所有 goroutine 的栈，需要调用 runtime.Stack() 或通过 profile 文件。本文聚焦于捕获 panic 时打印完整当前 goroutine 栈的方式，以及扩展至获取全部栈的方法。

基础用法：recover + debug.Stack()

package main

import (
    "fmt"
    "runtime/debug"
)

func main() {
    defer func() {
        if r := recover(); r != nil {
            fmt.Printf("捕获到 panic: %v\n", r)
            fmt.Println("完整调用栈：")
            debug.PrintStack() // 打印到标准错误
            // 或者使用 fmt.Printf("%s", debug.Stack()) 打印到其他输出
        }
    }()
    triggerPanic()
}

func triggerPanic() {
    var a []int
    _ = a[0] // 引发切片越界 panic
}

上述代码中：

使用 defer 注册一个匿名函数，在 main 返回前执行。
函数内调用 recover()，如果返回值非 nil，表示捕获到一个 panic。
通过 debug.PrintStack() 或 fmt.Println(string(debug.Stack())) 输出当前 goroutine 的完整调用栈。
这样即使程序已经 panic，我们也能看到从 triggerPanic 到 main 以及更深调用的所有层级。

获取所有 goroutine 的调用栈

若需要查看程序内所有 goroutine 的状态（类似 SIGQUIT 后的 dump），可以在 recover 内部使用 runtime.Stack() 函数。它能按照给定模式提取栈信息，并返回一个大 buffer。

package main

import (
    "fmt"
    "runtime"
    "runtime/debug"
)

func main() {
    defer func() {
        if r := recover(); r != nil {
            fmt.Printf("捕获到 panic: %v\n", r)

            // 获取所有 goroutine 的栈，设置足够大的 buffer
            buf := make([]byte, 1024*1024*16) // 16 MB
            n := runtime.Stack(buf, true) // true 表示所有 goroutine
            fmt.Printf("所有 goroutine 的栈信息：\n%s\n", buf[:n])

            // 也可以继续使用 debug.PrintStack() 打印当前 goroutine
            debug.PrintStack()
        }
    }()
    go func() {
        // 另一个 goroutine，可能处于死循环或等待
        select {}
    }()
    triggerPanic()
}

runtime.Stack(buf, true)：第二个参数 true 表示收集所有 goroutine 的栈。false 则只收集当前 goroutine。
需要预先分配足够大的 buf，防止截断。通常 1MB 以上足够，可根据程序规模调整。
输出所有 goroutine 的栈信息，可以清晰看到并发状态下各个 goroutine 的执行位置，便于定位并发问题。

将完整调用栈写入日志文件

生产环境中，不推荐直接输出到终端，而是写入日志文件或发送到监控系统。下面是一个将 panic 信息和完整栈写入文件的示例：

package main

import (
    "log"
    "os"
    "runtime/debug"
)

func main() {
    // 初始化日志文件
    f, err := os.OpenFile("panic.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()
    log.SetOutput(f)

    defer func() {
        if r := recover(); r != nil {
            log.Printf("panic recovered: %v\n%s", r, debug.Stack())
            // 也可以在这里发送告警、上传栈到错误追踪系统等
        }
    }()
    triggerPanic()
}

完整示例与输出对比

默认 panic 输出（无 recover）

panic: runtime error: index out of range [0] with length 0

goroutine 1 [running]:
main.triggerPanic()
        /path/to/main.go:9 +0x5a
main.main()
        /path/to/main.go:5 +0x27

使用 recover + debug.Stack() 后的输出

捕获到 panic: runtime error: index out of range [0] with length 0
完整调用栈：
goroutine 1 [running]:
runtime/debug.Stack()
        /usr/local/go/src/runtime/debug/stack.go:24 +0x5e
main.main.func1()
        /path/to/main.go:12 +0x45
panic({0x4b7c60, 0xc000012078})
        /usr/local/go/src/runtime/panic.go:884 +0x212
main.triggerPanic()
        /path/to/main.go:19 +0x25
main.main()
        /path/to/main.go:16 +0x39

可以看到，完整栈中包含了 runtime/debug.Stack() 自身的调用，以及从 triggerPanic 触发 panic 的完整链路，信息更丰富。

注意事项与最佳实践

不要在 recover 中再次 panic：如果在 recover 分支内又触发了 panic，会覆盖原始 panic，导致原始信息丢失。
避免阻塞日志输出：如果程序频繁 panic 并恢复，日志写入可能成为性能瓶颈，建议使用异步日志库。
结合 profile 和 dump：复杂问题可以结合 pprof 采集 goroutine profile，或设置环境变量 GOTRACEBACK 来控制崩溃时的栈打印粒度（例如 GOTRACEBACK=all 会让 Go runtime 在未恢复 panic 时输出所有 goroutine 栈）。
调试环境快速设置：export GOTRACEBACK=crash 可以让程序在 panic 时生成 core dump，配合 delve 等调试器分析。

总结

Go 语言默认的 panic 打印信息往往不够全面，通过 recover 捕获 panic 并借助 debug.Stack() 或 runtime.Stack()，可以自行输出更详细的调用栈，甚至获取所有 goroutine 的状态。这为排查并发问题、偶发性崩溃提供了强有力的支持。在工程实践中，将栈信息写入日志并接入告警系统，能大幅提升服务稳定性。

掌握这个技巧，就能在 Go 程序陷入 panic 时获得完整的“现场快照”，让调试不再摸黑。