• 可观测性
• 时序数据库
• 后端
• 指标监控

导读

github.com/pkg/errors是 Go 生态中经典的错误处理库，它为传统if err != nil { return err }的朴素写法提供了「保留原始错误价值」的上下文增强能力：通过Wrap为错误添加调用链信息与堆栈，通过Cause还原最底层根因，让排障日志从一串无意义文本变成可追溯的调用路径。本文以该库在 Cortex（一个水平可扩展、高可用、多租户的长期 Prometheus 存储系统）仓库中的 vendor 副本为核心骨架，结合其 README.md 官方文档、errors.go 与 stack.go 源码，以及 Cortex 各模块的真实调用方式，系统讲解它的核心 API、底层实现原理与大规模分布式系统中的实战模式。读完本文，你将掌握如何为错误添加上下文、如何递归还原根因、如何输出带堆栈的排障日志，并理解它与 Go 1.13 标准库errors的关系。

一、为什么需要 pkg/errors：传统 Go 错误处理的痛点

Go 的传统错误处理惯用法大致如下：

if err != nil { return err }

这种写法在调用栈中逐层递归返回后，最终得到的错误报告没有任何上下文与调试信息——你只知道「某个操作失败了」，却不知道失败发生在哪一层、经过哪些环节、最初的根因是什么。

pkg/errors的设计目标正是解决这个问题：它允许程序员在失败路径上添加上下文（context），同时不破坏错误的原始值。在 Cortex 这类由大量微服务（distributor、ingester、querier、store-gateway、ruler、alertmanager 等）组成的分布式系统中，一条请求会穿越多个进程与多个 goroutine，错误若不带上下文，线上排障几乎无从下手。

在 Cortex 仓库中，该依赖以 vendor 形式固化在 vendor/github.com/pkg/errors 目录下，对应版本为github.com/pkg/errors v0.9.1（见 go.mod 与 vendor/modules.txt）。

二、核心 API 全景：从创建错误到还原根因

2.1 创建带堆栈的错误：New与Errorf

errors.New(message)返回一个携带消息的错误，并在调用点记录堆栈；errors.Errorf(format, args...)则支持格式化消息，同样记录堆栈。源码实现（vendor/github.com/pkg/errors/errors.go）中，两者都构造了一个fundamental结构体：

func New(message string) error { return &fundamental{ msg: message, stack: callers(), } }

fundamental是一个「有消息、有堆栈、但没有 cause」的底层错误，是整条错误链的末端节点。

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

errors.Wrap(err, message)返回一个新错误，它在保留原始错误的同时追加一条消息，并在Wrap调用点记录堆栈。README 给出的经典示例：

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

Wrapf则支持格式化消息。从源码（vendor/github.com/pkg/errors/errors.go）看，Wrap内部其实是由两个更细粒度的操作组合而成：先包一层withMessage附加消息，再包一层withStack附加堆栈：

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

需要注意：Wrap与Wrapf对nil输入会返回nil，因此可以安全地用在err != nil分支之外，不会产生「包装了一个 nil 错误」的假错误。

2.3 拆解 Wrap：WithStack与WithMessage

如果需要对包装行为进行更细粒度的控制，库提供了两个组件函数：

• errors.WithStack(err)：仅为错误附加堆栈，不添加消息；
• errors.WithMessage(err, message)：仅为错误附加一条消息，不记录堆栈；
• WithMessagef为格式化版本。

对应的源码实现见 vendor/github.com/pkg/errors/errors.go 与 errors.go。它们同样遵循「输入 nil 返回 nil」的约定。

2.4 还原根因：Cause与causer接口

使用Wrap会构造出一个错误堆栈（stack of errors），每一层都为前一层添加了上下文。根据错误的性质，有时需要逆操作来取回原始错误进行检查。任何实现了下面这个接口的错误值都可以被errors.Cause检查（该接口虽未导出，但属于库稳定公共接口的一部分）：

type causer interface { Cause() error }

errors.Cause会递归查找最顶层的、没有实现causer的错误，那个错误被假定为最初的根因。README 中的典型用法是类型断言后分派处理：

switch err := errors.Cause(err).(type) { case *MyError: // handle specifically default: // unknown error }

源码（vendor/github.com/pkg/errors/errors.go）是一个简单而精巧的循环：不断断言causer接口并向下钻取，直到遇到不实现Cause()的错误为止。

2.5 一个完整的错误链示意

base := errors.New("connection refused") // 根因：无 cause ctx1 := errors.Wrap(base, "dial tcp") // withMessage + withStack ctx2 := errors.Wrap(ctx1, "query failed") // 再包一层 final := errors.Wrap(ctx2, "handle request") errors.Cause(final) == base // 递归还原到最初错误 fmt.Printf("%+v", final) // 完整上下文 + 每层调用点的堆栈

三、源码级原理：堆栈是如何被捕获与打印的

3.1callers()捕获调用点

New、Errorf、Wrap、Wrapf都会在调用点通过 stack.go 中的callers()捕获程序计数器：

func callers() *stack { const depth = 32 var pcs [depth]uintptr n := runtime.Callers(3, pcs[:]) var st stack = pcs[0:n] return &st }

它借助标准库runtime.Callers抓取最多 32 帧的程序计数器（Callers(3, ...)中的偏移 3 用于跳过库内部自身的栈帧）。

3.2Frame与StackTrace：把 PC 还原成文件名与行号

Frame表示栈中的一帧（vendor/github.com/pkg/errors/stack.go），通过runtime.FuncForPC可以把程序计数器还原为函数名、源文件路径与行号。StackTrace是Frame的切片，按**从内到外（最新调用点到最老调用点）**排列。

3.3 格式化输出协议：%s、%v与%+v

所有从该库返回的错误值都实现了fmt.Formatter，可直接被fmt包格式化。官方文档定义的动词语义如下：

Frame.Format（vendor/github.com/pkg/errors/stack.go）还支持%+s（函数名与相对 GOPATH 的源文件路径）、%d（行号）、%n（函数名）等细分动词。这意味着在 Cortex 的日志系统中，只需要对返回的错误使用%+v，即可把「哪个函数、哪个文件、哪一行」完整地烙进日志。

3.4 通过stackTracer接口手动提取堆栈

错误链上的任何一层都可能实现未导出的stackTracer接口，从而可以手动提取堆栈：

type stackTracer interface { StackTrace() errors.StackTrace }

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

四、与 Go 1.13 标准库的衔接：Is/As/Unwrap

Go 1.13 起标准库errors引入了错误链（error chain）与errors.Is/errors.As/errors.Unwrap。pkg/errors通过构建标签// +build go1.13提供了桥接实现（vendor/github.com/pkg/errors/go113.go）：

• Is(err, target)：判断错误链中是否存在与target相等的错误；
• As(err, target)：在错误链中查找第一个可赋值给target的错误并回填；
• Unwrap(err)：调用错误的Unwrap()方法返回链上的下一层。

同时，库内的withStack与withMessage包装器都实现了Unwrap() error（见 errors.go 与 errors.go），使整条由Wrap构造的链可以被标准库的链式 API 正常遍历。因此在新代码中，你可以同时享受%+v的堆栈输出与标准库Is/As的类型化判断，两者并不冲突。

五、Cortex 中的实战用法：从源码看真实调用模式

5.1 入口程序：配置加载阶段的上抛上下文

Cortex 的二进制入口 cmd/cortex/main.go 在读取与解析配置文件时使用errors.Wrap逐层附加业务语义：

return errors.Wrap(err, "Error reading config file") return errors.Wrap(err, "Error parsing config file")

这样，当配置错误最终被打印到日志时，操作者不仅能知道「解析失败」，还能看到具体失败于读取还是解析环节，以及%+v输出的源码调用位置。

5.2 Ingester：用Cause穿透包装层做精确判断

在 pkg/ingester/ingester.go 中，updateCachedShippedBlocks读取 shipper 元数据文件时，需要区分「文件不存在」与「其他读取错误」：

shipperMeta, err := shipper.ReadMetaFile(u.shipperMetadataFilePath) if os.IsNotExist(err) || os.IsNotExist(errors.Cause(err)) { // If the meta file doesn't exist it means the shipper hasn't run yet. shipperMeta = &shipper.Meta{} } else if err != nil { return err }

由于底层错误可能已经被多层Wrap包装，直接用os.IsNotExist(err)可能失效，因此这里同时检查原始错误与其 Cause，确保能正确识别os.ErrNotExist类型（pkg/ingester/ingester.go#L636-L644）。

更典型的场景是 ingest 写入路径中的软错误（soft error）分派（pkg/ingester/ingester.go#L1452-L1469）：

switch cause := errors.Cause(err); { case errors.Is(cause, storage.ErrOutOfBounds): sampleOutOfBoundsCount++ ... case errors.Is(cause, storage.ErrOutOfOrderSample): sampleOutOfOrderCount++ ... }

这里先用errors.Cause把错误链剥到最底层，再用errors.Is判断是否为 TSDB 的「越界」或「乱序」样本错误——这两类错误属于可以继续写入的软错误，会被统计后以 400 返回给客户端（Prometheus 收到 400 不会重试）。这种「剥根因 + 链式判断」的组合，正是pkg/errors与标准库能力协同的教科书级用法。

5.3 其他模块的典型模式

• 初始化失败上抛：store-gateway 在创建扫描器、索引缓存、chunk 字节池时使用errors.Wrap(err, "failed to create users scanner")等模式（见 pkg/storegateway/bucket_stores.go）；
• ingester 客户端流关闭：errors.Wrap(c.streamCtx.Err(), "ingester client stream connection closed")为流式连接的上下文错误补充业务信息（见 pkg/ingester/client/client.go）；
• 哨兵错误定义：pkg/ingester/ingester.go中大量使用errors.New定义包级哨兵错误（如errIngesterStopping、errLabelsOutOfOrder等，见 pkg/ingester/ingester.go#L110-L114），供后续errors.Is判断使用。

5.4 Cortex 对causer协议的本地扩展

Cortex 还在 pkg/util/errors/errors.go 中基于同样的Cause()协议做了自己的扩展：errors.WithCause(err, cause)用于为错误附加一个独立 cause（典型场景是把 gRPC 状态错误附加到对象存储错误上，见 pkg/storage/bucket/sse_bucket_client.go），errors.ErrorIs则提供基于函数谓词的链式遍历判断（用于识别「访问被拒绝」类错误，见 pkg/storegateway/bucket_stores.go）。这从侧面印证了causer接口作为稳定公共协议的价值：任何实现Cause() error的类型都可以被统一的链式工具所理解。

六、Roadmap 与维护状态：项目正处于维护模式

README 明确说明：随着 Go 2 错误提案（go2draft）的到来，该包已进入维护模式（maintenance mode）。其 1.0 版本的路线图是：

• 0.9：移除对 Go 1.9 与 Go 1.10 的支持，处理（尽可能多的）遗留 pull request；
• 1.0：最终发布版本。

同时，该包不再接受新功能的提案，但仍欢迎 pull request、bug 修复与 issue 报告；提交 PR 前建议先通过 issue 讨论变更。Cortex 仓库中固化的正是 0.9.1 版本。这也意味着：在新项目中，优先考虑标准库errors的链式能力；而在维护中的既有项目（如依赖%+v堆栈输出的 Cortex），pkg/errors仍然是稳定可靠的选择。

七、实战建议与注意事项

1. 在关键错误路径使用Wrap/Wrapf，为每一层调用补充「做了什么」的上下文；日志统一用%+v输出，即可获得完整堆栈。
2. 判断错误类型时先Cause再Is：如 Cortex ingester 的做法（errors.Cause剥根因 +errors.Is判断），避免被包装层干扰。
3. 哨兵错误用errors.New定义包级变量，配合errors.Is/errors.Cause做精确匹配，而不是用字符串比较。
4. 注意Wrap对nil的安全语义：传入 nil 会返回 nil，无需额外判空。
5. 理解新旧 API 的边界：pkg/errors处于维护模式且依赖 0.9.x，新代码可优先使用标准库fmt.Errorf的%w包装 +errors.Is/As；若项目已深度使用%+v堆栈输出，继续使用pkg/errors同样合理。

参考文件

• 官方 README：本文核心依据，含 Wrap/Cause 示例与 Roadmap
• errors.go 源码：New/Errorf/Wrap/Wrapf/WithStack/WithMessage/Cause 的实现
• stack.go 源码：Frame/StackTrace 与格式化协议
• go113.go 源码：Go 1.13 的 Is/As/Unwrap 桥接
• Cortex 入口程序：配置加载阶段的 Wrap 用法
• ingester 实现：Cause 穿透包装层的实战示例
• Cortex 错误扩展：基于 causer 协议的本地扩展
• 依赖版本声明：github.com/pkg/errors v0.9.1

• 可观测性
• 时序数据库
• 后端
• 指标监控