Go语言pkg/errors包带堆栈错误创建函数写法

在Go语言的实际开发中，错误处理一直是开发者既爱又恨的议题。标准库的errors.New使用简便，但存在一个明显缺陷：它返回的错误对象不包含任何调用堆栈信息。当错误在多层函数调用间传递时，你无法得知它最初在哪一行代码产生。线上排查时，面对一个泛泛的“failed to open file”，只能对着代码干瞪眼，却找不到是哪个os.Open调用出了问题——这恐怕是不少Go开发者都踩过的坑。

解决问题的关键，在于引入github.com/pkg/errors这个第三方包。虽然它不是官方标准库，但其核心价值在于：将错误的创建与堆栈的捕获紧密绑定。不是简单地“附加堆栈”，而是“在错误诞生的那一刻，立即快照完整的调用链”。这样一来，无论后续如何包装、传递，原始位置都不会丢失。

来看个直观的对比：

err := errors.New("read timeout") // 无堆栈
err := pkgerrors.New("read timeout") // 自动捕获当前行号和调用链

为什么errors.New不包含堆栈，而你需要它

标准库的errors.New返回的错误对象，不携带调用堆栈。一旦错误在多层函数中传递，你无法确定它最初在哪一行生成。调试时只能看到“failed to open file”，却找不到是哪个os.Open调用引起的——这已成为线上排查中最令人头疼的根源之一。

推荐使用github.com/pkg/errors（注意：不是官方errors包），其核心价值在于将错误创建与堆栈捕获绑定在一起。关键不在于“添加堆栈”，而在于“在错误诞生那一刻就快照堆栈”，后续无论怎样包装、传递，原始位置都不会丢失。

pkgerrors.Wrap与pkgerrors.WithStack的区别是什么

这两个函数都会添加堆栈信息，但触发时机不同，容易混用导致堆栈重复或遗漏捕获。

• pkgerrors.WithStack(err)：仅为已有错误err补充一个新堆栈帧（即当前调用点），不改变原始错误内容，适用于“透传错误但标记当前位置”的场景
• pkgerrors.Wrap(err, "failed to parse config")：在包裹错误的同时，既添加新消息，又记录当前堆栈——这是最常用的场景
• 不要对nil错误调用Wrap，否则会导致panic；应先判空，或使用pkgerrors.WrapIf（v0.9.1+）
• 如果上游错误已经是pkgerrors类型，Wrap会合并堆栈，而非简单叠加；但多次调用WithStack可能产生冗余帧

如何打印包含完整堆栈的错误信息

直接使用fmt.Println(err)或log.Printf("%v", err)只会显示错误消息，不会输出堆栈信息。必须使用%+v格式化动词来获取堆栈。

示例：

err := pkgerrors.Wrap(io.EOF, "reading header")
fmt.Printf("%+v\n", err) // 输出含文件名、行号、调用链的完整堆栈

注意：%+v是pkgerrors自定义的格式化行为，标准fmt对其他错误类型无效；如果使用slog或结构化日志，需要调用pkgerrors.MarshalJSON或手动提取pkgerrors.Cause(err).Error()以避免panic。

常见陷阱：在HTTP handler中使用log.Printf("%v", err)记录日志，结果日志中只有“internal error”，堆栈信息完全丢失。

Go 1.13+官方errors包与pkgerrors如何共存

官方errors.Is和errors.As能够识别pkgerrors包装的错误，但前提是底层错误没有被覆盖。例如：

err := pkgerrors.Wrap(os.ErrNotExist, "config missing")
errors.Is(err, os.ErrNotExist) // true
errors.As(err, &pathErr)          // true，可提取 *os.PathError

但如果你使用fmt.Errorf("wrap: %w", err)包裹pkgerrors错误，Go官方的%w会剥离pkgerrors的堆栈结构，只留下标准错误链——堆栈信息就此丢失。

因此，在混合使用时，坚持使用pkgerrors.Wrap替代fmt.Errorf(...%w...)；所有错误创建和包装统一走pkgerrors，避免中间混入标准fmt.Errorf。

真正麻烦的是团队中有人悄悄改变了包装方式，等到线上报错出现堆栈断层，才想起查git blame。