Go runtime/debug.SetCrashOutput 怎样把崩溃输出转到文件

如果 Go 服务发生未处理的 panic 或其他致命错误，默认信息会写到标准错误。想额外保留一份崩溃报告，可以使用 runtime/debug.SetCrashOutput。它接收一个 *os.File 和 debug.CrashOptions，成功后把崩溃输出复制到这个文件，同时仍保留标准错误输出。

官方文档：https://pkg.go.dev/runtime/debug#SetCrashOutput

最小可用写法是先打开一个追加写入文件，再调用 debug.SetCrashOutput；调用返回后可以关闭原文件句柄。重复调用只保留最后一次配置，传入 nil 可以关闭额外输出。

先分清 SetCrashOutput 管什么

SetCrashOutput 只增加一个额外输出目标，不会把标准错误重定向掉，也不是 panic 恢复器。程序最多保留一个额外崩溃输出文件，第二次调用会覆盖第一次的目标。

它适合把崩溃文本交给独立的文件采集器、容器卷或监控进程。日志文件的目录、权限、轮换和上传仍由应用或部署系统负责。

用追加文件接收崩溃输出

打开文件时要先处理目录和权限错误。下面的初始化函数只负责配置额外输出，调用方可以在启动阶段决定配置失败时是退出、降级到标准错误，还是交给外部日志系统。

package main

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

func setupCrashOutput(path string) (func(), error) {
    // 追加写入，避免每次启动覆盖已有的崩溃记录；权限只给文件所有者。
    f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
    if err != nil {
        return nil, fmt.Errorf("打开崩溃输出文件: %w", err)
    }

    // SetCrashOutput 会复制文件描述符；这里只需在配置失败时关闭原句柄。
    if err := debug.SetCrashOutput(f, debug.CrashOptions{}); err != nil {
        _ = f.Close() // 配置失败时释放已经打开的资源。
        return nil, fmt.Errorf("配置崩溃输出: %w", err)
    }
    _ = f.Close() // 配置成功后也可以关闭调用方持有的句柄。

    return func() {
        // 传入 nil 关闭额外输出；标准错误仍由运行时保留。
        _ = debug.SetCrashOutput(nil, debug.CrashOptions{})
    }, nil
}

这里的 0o600 只允许文件所有者读写，适合崩溃报告可能包含请求参数、路径或堆栈上下文的场景。若目录不存在，OpenFile 会失败，不能把“配置成功”当成默认结果。

为什么调用后可以关闭文件

官方文档明确说明，SetCrashOutput 会复制传入文件的文件描述符。因此成功返回后，调用方可以关闭 f，不会让运行时失去已经配置的额外输出目标；这也是上面把 Close 写在成功分支的原因。

但关闭时机不能提前到 SetCrashOutput 之前。正确顺序是“打开文件、配置输出、检查错误、再关闭原句柄”。如果打开失败或配置返回错误，仍要显式关闭当前句柄，避免启动失败路径泄漏资源。

重复配置、关闭和并发崩溃的边界

如果要切换到新文件，只需再次调用 SetCrashOutput(newFile, debug.CrashOptions{})。它会覆盖旧的额外目标；调用成功后仍按同样规则关闭调用方持有的 newFile。不需要额外维护一组输出文件。

如果要停止额外输出，调用 debug.SetCrashOutput(nil, debug.CrashOptions{})。这只关闭额外目标，不等于关闭标准错误，也不会阻止运行时报告崩溃。

还有一个容易忽略的边界：如果替换配置的同时正在发生崩溃，部分已经开始的输出可能继续写到旧文件，即使新的调用已经返回。这不是文件轮换失败，而是并发替换期间允许存在的尾部交错。需要严格按崩溃事件切分时，应由采集端按时间、进程实例或报告标记归档，而不是依赖一次调用瞬间完成切换。

上线前的四项检查

• 目录由部署系统提前创建，运行用户对目录和文件拥有明确权限。
• 文件使用追加模式，轮换时先准备新文件，再调用一次 SetCrashOutput 完成切换。
• 配置错误要保留真实错误；不要在没有文件句柄时假装已经启用崩溃文件。
• 如果要交给监控进程，可把可写的文件描述符或管道交给它，但监控进程的启动、退出和报告保存仍是独立设计。

常见问题

SetCrashOutput 会替代标准错误吗？不会。它配置的是一个额外输出目标，标准错误仍然保留。

传入 nil 后还能再次启用吗？可以。重新打开目标文件并再次调用即可；调用顺序决定当前唯一的额外输出目标。

它能捕获所有业务错误吗？不能。它针对未处理 panic 和运行时致命错误，不替代业务层的 error 返回、日志记录和优雅退出策略。