在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。
