lazydocker 仓库中的 github.com/pkg/errors：Go 错误添加上下文与追溯根因的实用指南

github.com/pkg/errors 是 Go 生态中经典的错误处理原语库，它以"在错误链上逐层包装上下文、同时保留原始错误价值"为设计目标，解决了传统 if err != nil { return err } 写法导致错误信息失真的问题。本指南以该库在 lazydocker 仓库中的 vendored 拷贝（vendor/github.com/pkg/errors）为主线，完整讲解 Wrap/Wrapf、Cause、WithStack、WithMessage 以及 %+v 堆栈打印等 API 的语义与底层实现，并说明它与 Go 1.13 标准库 errors 的互操作方式。读完本文，你将能在自己的 Go 项目中熟练构建带上下文的错误链，并在日志中还原完整的函数调用栈。

传统错误处理方式为何不够

Go 传统的错误处理习惯大致是：

if err != nil {
    return err
}

这种写法在调用栈中被逐层递归地复制后，最终产出的错误报告往往缺乏上下文和调试信息——底层抛出的 "no such file" 到了顶层只剩下干巴巴的字符串，开发者不知道它发生在哪一步操作、经过哪条调用路径。

pkg/errors 的解法是：允许程序员在代码的失败路径上逐层添加上下文（context），并且"不以破坏原始错误价值为代价"。也就是说，每一层包装都会保留底层错误作为"根因"，同时新挂载本层的说明文字与当时的调用位置信息，最终形成一条可逐级拆解的包装链。

在 lazydocker 仓库中，该库以 v0.9.1 版本作为间接依赖出现在 go.mod 中（标记为 // indirect），并按 Go 的 vendor 机制完整固化在 vendor/github.com/pkg/errors 目录下，包含源码文件：

• errors.go：New/Errorf/Wrap/Wrapf/WithStack/WithMessage/Cause 等核心 API 的实现；
• stack.go：Frame/StackTrace 类型与栈帧格式化逻辑；
• go113.go：面向 Go 1.13+ 的 Is/As/Unwrap 兼容封装；
• README.md、LICENSE（BSD-2-Clause）、Makefile、appveyor.yml。

值得说明的是：lazydocker 的业务源码（如 main.go、pkg/commands/errors.go）大多直接使用功能近似的 github.com/go-errors/errors，而非直接 import 本包；pkg/errors 主要通过依赖树以 vendor 形式随仓库分发，其设计与 API 语义正好可以作为理解 Go 错误链式处理思想的范本。

为错误添加上下文：Wrap 与 Wrapf

errors.Wrap 是包中最核心的函数：它返回一个新的错误，为原始错误添加上下文，同时在调用 Wrap 的位置记录一份堆栈快照。官方文档给出的例子：

_, err := ioutil.ReadAll(r)
if err != nil {
    return errors.Wrap(err, "read failed")
}

当上层打印该错误时，既能看见 "read failed" 这一层业务上下文，又能顺着底层错误继续排查真正的失败原因。

从 errors.go 的源码可以看出 Wrap 的实际结构（v0.9.1 版本）：

func Wrap(err error, message string) error {
    if err == nil {
        return nil
    }
    err = &withMessage{
        cause: err,
        msg:   message,
    }
    return &withStack{
        err,
        callers(),
    }
}

也就是说，一次 Wrap 等价于"先包一层 withMessage（携带说明文字），再在外面包一层 withStack（携带栈帧）"。返回的对象同时实现了 Cause() error 与 Unwrap() error 方法，因此既能被本包的 Cause 解包，也能被 Go 1.13 标准的错误链机制识别。

Wrapf 则提供格式化版本，适合带参数构造上下文消息：

func Wrapf(err error, format string, args ...interface{}) error

其内部用 fmt.Sprintf(format, args...) 生成消息后再执行与 Wrap 相同的包装逻辑（见 errors.go）。两个函数都遵循 nil 安全约定：当 err 为 nil 时直接返回 nil，不会包装出"假错误"。

withMessage 结构体的 Error() 方法把上下文与根因拼接成 msg + ": " + cause.Error() 的形式（errors.go），这正是错误信息看起来层层递进的原因。

拆分原语：WithStack 与 WithMessage

如果只需要"记录栈"或"只加一句话"中的某一种能力，包提供了 Wrap 的拆分版本：

• WithStack(err)：仅在调用点给错误附加一份堆栈，不加任何消息；
• WithMessage(err, message)：仅给错误附加一条消息，不记录新栈；
• 对应的 WithMessagef(err, format, args...) 是带格式化的消息版。

// 只关心调用位置、不想改写错误文案
return errors.WithStack(err)

// 只补充业务语义、不关心在此处重取栈
return errors.WithMessage(err, "open config file")

它们的实现同样遵守 nil 安全原则——入参为 nil 时返回 nil（errors.go）。可以看到 WithStack 内部返回 &withStack{err, callers()}，与 Wrap 最外层完全一致；而 WithMessage 则只返回 &withMessage{cause, msg}。这意味着你可以像搭积木一样自由组合"栈"与"消息"两种注解，实现细粒度的错误链路定制。

追溯根因：errors.Cause 与 causer 接口

使用 errors.Wrap 会构建出一层套一层的错误栈。根据错误类型的不同，上层代码往往需要"反转"包装过程、还原出最初的原始错误来做类型判断或针对性处理。为此包定义了如下约定——任何实现了该接口的错误值都可以被 errors.Cause 检视：

type causer interface {
    Cause() error
}

需要强调：虽然 causer 是未导出接口，但它被视为该包稳定公共接口的一部分（见 errors.go 的注释），任何第三方错误类型都可以实现它来参与解包。

errors.Cause 会递归地向上剥离包装，直到找到最顶层那个"不再实现 causer"的错误——它被假定为原始根因：

switch err := errors.Cause(err).(type) {
case *MyError:
    // 对特定错误类型做专门处理
    handleMyError(err)
default:
    // 未知错误
    handleUnknown(err)
}

从源码实现看，Cause 通过类型断言循环探测 causer 接口并逐层下钻，直到遇到不实现该接口的错误或 nil 为止（errors.go）。这解释了为什么只要链路上每一层都通过 Wrap/WithStack/WithMessage 生成（它们均携带 Cause() 方法），根因就能被稳定地还原出来。

格式化打印：%s、%v 与 %+v

包内返回的所有错误值都实现了 fmt.Formatter，可直接由 fmt 系列函数格式化。支持的动词如下：

动词	行为
%s	打印错误文本；若错误带 Cause，则递归打印整条原因链
%v	等价于 %s
%+v	扩展格式：错误链上每个 Frame 的堆栈信息都会被详细打印

因此，日志里常见的用法是：

log.Printf("operation failed: %+v", err)

输出会包含每一层包装对应的文件、行号、函数名，让一次调用失败的完整调用路径一目了然——这正是 pkg/errors 相比裸字符串错误最具实战价值的特性。

stackTracer 接口与手工取栈

New、Errorf、Wrap、Wrapf 在调用点都会记录栈。这些栈信息可以通过如下接口取回：

type stackTracer interface {
    StackTrace() errors.StackTrace
}

与 causer 一样，它虽未导出，但同样是稳定公共接口的一部分。StackTrace 的类型定义为 type StackTrace []Frame，每个 Frame 代表栈中的一个调用点，并且 Frame 本身支持 fmt.Formatter。文档示例给出手工遍历方式：

if err, ok := err.(stackTracer); ok {
    for _, f := range err.StackTrace() {
        fmt.Printf("%+s:%d\n", f, f)
    }
}

Frame 与 StackTrace 的格式化动词

结合 stack.go 的源码，Frame 支持的格式化动词比包级错误更细：

动词	含义
%s	源文件名（取路径最后一段）
%+s	函数名 + 换行缩进 + 相对 GOPATH 的完整源文件路径
%d	源文件行号
%n	函数名
%v	等价于 %s:%d（文件:行号）

StackTrace 的格式化为 %s 时列出各帧源文件，%v 列出文件+行号，而 %+v 会对每个帧打印 文件名、函数名、行号 的完整细节（stack.go）。实现层面，每个 Frame 内部保存的是"程序计数器 + 1"（type Frame uintptr），通过 runtime.FuncForPC 反查函数与文件信息；callers() 使用深度为 32 的固定缓冲调用 runtime.Callers(3, ...) 采集调用点（stack.go）。

与 Go 1.13 标准库 errors 的互操作

随着 Go 1.13 引入标准库 errors.Is/errors.As/errors.Unwrap，pkg/errors 在 go113.go（带 // +build go1.13 构建标签）中提供了对应转发：

func Is(err, target error) bool { return stderrors.Is(err, target) }
func As(err, target interface{}) bool { return stderrors.As(err, target) }
func Unwrap(err error) error { return stderrors.Unwrap(err) }

即编译于 Go 1.13+ 时，本包的 Is/As/Unwrap 直接委托给标准库实现（go113.go）。同时，本包的包装类型（withStack、withMessage）都额外实现了 Unwrap() error（见 errors.go），保证由 Wrap 生成的错误链也能被标准库的 Is/As 正常遍历。这带来一个重要好处：老项目升级 Go 1.13 后，不必重写全部错误处理代码，仍可用 errors.Is(err, os.ErrNotExist) 这类现代写法来判定根因类型。

顶层错误原语：New 与 Errorf

当错误链的"源头"由你亲自创建时，使用：

err := errors.New("config file missing")
err := errors.Errorf("port %d is occupied", 8080)

从 errors.go 看，两者都返回一个 fundamental 结构（msg + 调用点栈快照），即"自带消息与栈、但没有更底层的 cause"。Errorf 内部先经 fmt.Sprintf 生成消息，再走与 New 完全相同的建栈流程。在 lazydocker 中，类似"每种渲染项必须返回等长字符串""不支持的 detailization 格式"这类基础断言错误，正是以 errors.New/格式化错误的形式作为失败源头抛出（见 pkg/utils/utils.go 及对应测试 pkg/utils/utils_test.go）。

Roadmap：维护模式与 Go 2 错误提案

由于 Go 2 错误处理设计提案 的推进，该包已进入维护模式（不再接受新功能提案，但仍欢迎 PR、bug 修复与 issue 报告）。原文档给出的 1.0 发布路线图为：

• 0.9：移除对 Go 1.9 / Go 1.10 之前版本的支持，尽可能处理遗留 PR；
• 1.0：最终正式发布。

仓库中锁定的正是处于该路线图上的 v0.9.1 版本（go.mod 第 68 行）。这意味着其 API 已经相当稳定，适合作为学习 Go 错误处理范式和长期依赖使用。

API 速查总结

函数	作用	nil 安全	记录栈
New(msg)	创建带消息与栈的顶层错误	不适用	是
Errorf(format, args...)	格式化版 New	不适用	是
Wrap(err, msg)	加消息 + 记栈	返回 nil	是
Wrapf(err, format, args...)	格式化版 Wrap	返回 nil	是
WithStack(err)	只记栈	返回 nil	是
WithMessage(err, msg) / WithMessagef(...)	只加消息	返回 nil	否
Cause(err)	递归剥离到最底层根因	返回 nil	—
Is / As / Unwrap	Go 1.13+ 标准库兼容转发	—	—

使用口诀可概括为：源头用 New/Errorf，中间层用 Wrap/Wrapf 或按需拆分的 WithStack/WithMessage，判定根因用 Cause 或 errors.Is/errors.As，排障日志务必 %+v 打印完整调用栈。本包按 BSD-2-Clause 许可发布（见 vendor/github.com/pkg/errors/LICENSE），示例与源码可随时在 vendor/github.com/pkg/errors 目录中对照研读。