fmt.Errorf 支持错误包装需用 %w 动词,%v 会丢失嵌套关系导致 errors.Is/As 失效;正确写法是单 %w 包装可 Unwrap 的 error,多层需链式调用,避免用 errors.New 等不可展开类型。

Go 1.13+ 的 fmt.Errorf 支持错误包装(wrap),但必须用 %w 动词,用错就丢失嵌套关系。
为什么 fmt.Errorf("failed: %v", err) 不算 wrap
这种写法只是把原始错误转成字符串拼进去,返回的是一个纯 *fmt.wrapError(实际是 fmt.errorString),底层 Unwrap() 方法返回 nil,后续调用 errors.Is() 或 errors.As() 全部失效。
常见错误现象:errors.Is(err, io.EOF) 返回 false,即使原始错误确实是 io.EOF。
- 正确做法:必须用
%w,且只允许一个%w占位符 -
%w后面的值必须是实现了error接口的类型,不能是string或其他类型 - 多个错误想串联?得链式调用:
fmt.Errorf("level2: %w", fmt.Errorf("level1: %w", originalErr))
fmt.Errorf 和 errors.Wrap(来自 github.com/pkg/errors)的区别
Go 标准库的 fmt.Errorf + %w 是轻量、无依赖、符合 errors 包语义的方案;pkg/errors.Wrap 是旧时代方案,自带堆栈追踪,但 Go 1.17+ 的 runtime/debug.Stack() 或第三方工具(如 github.com/ztrue/tracerr)已能更好替代。
立即学习“go语言免费学习笔记(深入)”;
- 标准库不记录堆栈,
fmt.Errorf只做包装,性能开销极小 -
pkg/errors在 Go 1.13+ 后已不推荐用于新项目,它的Wrap返回类型不是标准error的子集(含额外方法),和errors.Is/As兼容但略重 - 如果已有代码用
pkg/errors,可逐步替换为fmt.Errorf("%w", ...),无需改调用逻辑
怎么安全地多层包装并保留原始错误类型
关键点在于每次包装都只用一个 %w,且确保被包装对象本身支持 Unwrap()(即它自己也是用 %w 或实现了该方法的 error)。
示例:
func readConfig() error {
b, err := os.ReadFile("config.yaml")
if err != nil {
return fmt.Errorf("read config file: %w", err) // ← 第一层 wrap
}
if len(b) == 0 {
return fmt.Errorf("config is empty: %w", errors.New("empty")) // ← 这里 %w 传的是 errors.New,它不支持 Unwrap,所以这层“断链”
}
return yaml.Unmarshal(b, &cfg)
}
// 正确写法:空配置也应返回可 unwrap 的 error,比如:
return fmt.Errorf("config is empty: %w", &customEmptyError{})
- 避免用
errors.New或fmt.Errorf(无%w)作为被包装对象,否则链在此中断 - 若需带上下文又不想引入新类型,可用
fmt.Errorf("msg: %w", fmt.Errorf("inner"))—— 但注意两层都是标准 wrap,errors.Is仍能穿透 - 调试时用
fmt.Printf("%+v\n", err)可看到完整包装链(需 Go 1.17+)
检查是否真的 wrap 成功了
别只靠日志字符串判断。最直接的方式是调用 errors.Unwrap() 看是否非 nil,或用 errors.Is() 匹配原始错误值。
-
errors.Unwrap(err)返回nil→ 没有包装,或包装用了%v/%s -
errors.Is(err, os.ErrNotExist)返回true→ 包装链中存在该错误,且每层都用了%w - 注意:
errors.As()要求目标指针类型实现了error接口,且原始错误(或某层)是该类型的实例
容易被忽略的是:包装链越长,Unwrap() 调用次数越多,但标准库不做深度限制;不过人为嵌套超 10 层基本说明设计有问题。


















