如何在Golang中捕获panic并记录栈信息

在Go语言开发中，panic是一种终止正常控制流的机制，常用于表示程序遇到了无法继续运行的错误。如果不在合适的时机进行捕获，panic会导致整个进程退出，尤其是在并发密集的服务中，一个协程的panic可能让线上系统瞬间不可用。因此，掌握如何捕获panic并完整记录栈信息，是编写健壮Go服务的基本功。

理解panic与recover的基本原理

Go中的panic会沿着调用栈向上抛，直到被recover拦截或者程序崩溃。recover是一个内建函数，只能在defer函数中生效。当defer函数中的recover被调用且当前正处于panic状态时，它会返回panic的值并停止 panic 传播，使程序恢复正常执行流程。

需要注意的是，recover必须直接写在defer函数体里，不能通过其他函数间接调用，否则会返回nil。很多初学者把recover封装到一个工具函数里然后放在defer中，结果发现并没有捕获到panic，就是这个原因。下面是一段错误用法示例：

package main

import "fmt"

func guard() {
    if r := recover(); r != nil {
        fmt.Println("recovered:", r)
    }
}

func main() {
    defer guard() // 错误：recover不在defer直接调用的函数体内直接执行
    panic("boom")
}

正确的方式是将recover直接置于defer的匿名函数中。这样当panic触发时，延迟调用的匿名函数会执行，其中的recover才能生效并截获异常。

使用runtime.Stack获取完整栈信息

仅仅调用recover拿到panic的值还不够，因为这个值通常只说明发生了什么错误，却无法告诉我们错误发生在哪一行、经过了哪些函数调用。Go标准库的runtime包提供了Stack函数，可以把当前goroutine的栈帧内容写入字节切片。

下面的示例展示了在defer中同时recover并收集栈信息，然后将栈打印到标准错误。buf大小一般给足够空间，例如4096字节，若栈较长可循环扩容。这种方式适合在简单命令行工具或测试中使用。

package main

import (
    "fmt"
    "runtime"
)

func main() {
    defer func() {
        if r := recover(); r != nil {
            buf := make([]byte, 4096)
            n := runtime.Stack(buf, false) // false表示只当前goroutine
            fmt.Printf("panic: %vnstack: %sn", r, buf[:n])
        }
    }()

    causePanic()
}

func causePanic() {
    var m map[string]int
    m["key"] = 1 // 向nil map写入，触发panic
}

runtime.Stack的第二个参数如果传true，则会把所有goroutine的栈都 dump 出来，在排查死锁或协程暴涨时非常有用，但输出量较大，生产环境应谨慎使用或仅在特定调试开关打开时才开启。

更便捷的debug.Stack方法

除了runtime.Stack，runtime/debug包提供了Stack函数，它直接返回当前所有goroutine的栈字符串，使用上更简洁。对于大多数Web服务，推荐在统一的中间件或协程包装器里使用debug.Stack来记录。

下面的代码演示了一个通用的安全执行函数，任何可能panic的业务逻辑都可以包一层，既捕获异常又拿到完整栈，还能把栈作为字符串交给日志组件。

package main

import (
    "fmt"
    "runtime/debug"
)

func safeRun(fn func()) (err error) {
    defer func() {
        if r := recover(); r != nil {
            stack := debug.Stack()
            err = fmt.Errorf("panic: %v, stack: %s", r, stack)
        }
    }()
    fn()
    return nil
}

func main() {
    e := safeRun(func() {
        panic("database connection lost")
    })
    if e != nil {
        fmt.Println(e)
    }
}

debug.Stack默认包含所有goroutine的信息，因此即使你在某个子协程中调用它，也能看到主协程及其他协程的调用情况。不过要注意，返回的字符串可能很大，记录到日志时需考虑磁盘与采集性能。

在HTTP服务中统一捕获panic

对于使用net/http构建的接口服务，可以为路由套一层中间件，在中间件里defer recover并记录栈，避免单个请求panic拖垮整个服务。这样每个请求都有独立的恢复逻辑，且栈信息可附带请求ID方便追溯。

以下示例展示了一个简单的日志中间件，它把panic的栈通过标准日志输出，并给客户端返回500。真实项目中可替换为结构化日志或上报到哨兵等平台。

package main

import (
    "log"
    "net/http"
    "runtime/debug"
)

func recoverMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                log.Printf("panic in %s %s: %vn%s", r.Method, r.URL.Path, rec, debug.Stack())
                http.Error(w, "internal server error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        panic("unexpected nil pointer")
    })
    http.ListenAndServe(":8080", recoverMiddleware(mux))
}

该模式的优点是业务处理函数完全不需要关心恢复逻辑，所有panic都被收敛在网关层。但如果程序中有单独启动的goroutine处理后台任务，仍需在goroutine入口自行加defer recover，因为HTTP中间件管不到它们。

协程中的panic捕获注意事项

Go鼓励并发，但每个goroutine都是独立的调用栈，主协程的recover无法捕获其他协程的panic。很多后台任务用go func()启动后忘记加保护，一旦panic就会导致进程退出。

建议封装一个GoSafe辅助函数，强制所有协程都经过它启动。如下代码在启动协程时自动加上defer recover和栈记录，减少人为遗漏。

package main

import (
    "fmt"
    "runtime/debug"
)

func GoSafe(fn func()) {
    go func() {
        defer func() {
            if r := recover(); r != nil {
                fmt.Printf("goroutine panic: %vn%s", r, debug.Stack())
            }
        }()
        fn()
    }()
}

func main() {
    GoSafe(func() {
        var s []int
        _ = s[0] // 切片越界panic
    })
    select {} // 阻塞主协程观察输出
}

这种封装让团队在写并发代码时形成统一规范，也便于以后在GoSafe内部接入链路追踪或告警。不过要注意，如果fn里又启动了未受保护的协程，那些子协程依然需要自己处理。

将栈信息写入日志文件的最佳实践

记录栈信息时，不应只打印到控制台。生产环境通常将日志输出到文件，并配合日志级别和轮转。可以使用标准库log或第三方库如zap，将recover得到的栈作为错误字段写入。

下面的表格对比了几种常见记录方式的适用场景：

无论选择哪种，都建议把panic值、栈字符串、发生时间以及能关联请求的上下文（如user_id、trace_id）一起保留。这样在故障复盘时，才能快速定位是哪次发布、哪个接口、哪段代码路径引发的问题。

小结与常见误区

一个常见误区是认为recover能捕获所有错误。实际上，recover只能处理panic，不能拦截普通的error返回值，因此该用error的地方仍应显式返回。另一个误区是在库函数内部悄悄recover吞掉panic，这会掩盖调用方的真实bug，除非是明确的协程边界。

总的来说，在Golang中捕获panic并记录栈信息，核心就是：在defer中直接调用recover，用runtime.Stack或debug.Stack拿栈，在统一入口和协程边界做防护，并把栈送进可靠的日志系统。做好这几步，你的Go服务在面临意外异常时就能做到心中有数、排查有据。

Golangpanicstack_trace修改时间：2026-08-06 20:45:43