Go fmt.Errorf 用 %v 而不是 %w 会失去什么

在 Go 代码里给错误补充“读取配置失败”“加载用户失败”这类上下文时，fmt.Errorf 的格式动词很容易写成 %v。这样做通常不会改变打印出来的错误文本，却会切断错误链：调用方再用 errors.Is 或 errors.As 时，找不到原来的哨兵值或具体类型。

结论：%v 只把底层错误格式化进新文本；%w 在保持相同可读文本的同时保留 Unwrap 关系。是否选 %w，关键不在“信息更多”，而在当前函数是否愿意把底层错误作为 API 的一部分交给调用方。

先看同一条错误为什么会得到两种能力

假设底层读取器返回一个包级哨兵错误。上层要补充文件名，分别用两个函数包装它：

package main

import (
    "errors"
    "fmt"
)

var errStoreOffline = errors.New("存储服务不可用")

func withText(path string) error {
    // 只把底层错误写进文本，不向调用方承诺它的身份。
    return fmt.Errorf("读取 %s 失败：%v", path, errStoreOffline)
}

func withChain(path string) error {
    // 保留底层错误，调用方可以继续用 errors.Is 判断。
    return fmt.Errorf("读取 %s 失败：%w", path, errStoreOffline)
}

func main() {
    fmt.Println(withText("settings.json"))
    fmt.Println(withChain("settings.json"))
    fmt.Println(errors.Is(withText("settings.json"), errStoreOffline))
    fmt.Println(errors.Is(withChain("settings.json"), errStoreOffline))
}

前两行打印的文本都可以是“读取 settings.json 失败：存储服务不可用”。但最后两个判断分别是 false 和 true。%v 只完成格式化；%w 让返回的错误实现可供 errors.Is 遍历的解包关系。

调用方真正失去的是 Is 和 As 的判断入口

errors.Is 适合判断“是不是某个已约定的错误”，例如是否需要重试、返回未找到，或切换到降级路径。errors.As 则适合提取某一类错误的附加字段。它们都依赖错误链；如果中间层用 %v 把错误重新变成普通文本，后面的调用方只能比较整句字符串，或者永远得不到原始类型。

type FieldError struct {
    Field string
    Cause error
}

func (e *FieldError) Error() string { return e.Field + "：" + e.Cause.Error() }
func (e *FieldError) Unwrap() error { return e.Cause }

func loadProfile() error {
    // 让调用方既能识别字段错误，也能继续检查底层原因。
    return fmt.Errorf("加载资料失败：%w", &FieldError{
        Field: "头像地址",
        Cause: errStoreOffline,
    })
}

func handle() {
    err := loadProfile()
    var fieldErr *FieldError
    if errors.As(err, &fieldErr) {
        fmt.Println("字段：", fieldErr.Field)
    }
    if errors.Is(err, errStoreOffline) {
        fmt.Println("可以进入存储降级分支")
    }
}

这里的 Unwrap 是自定义类型继续暴露原因的桥梁，fmt.Errorf("...%w", err) 是上层补充上下文的桥梁。只要其中任意一层改成 %v，这条链就会在那一层停止。

选 %w 前先判断是否要公开实现细节

%w 不是无条件更好的写法。一个包如果在文档或稳定行为中允许调用方识别某个哨兵错误，那么返回 %w 才能让这个约定持续工作。比如上层服务明确承诺“资源不存在时可用 errors.Is(err, ErrNotFound) 判断”，就应该保留这条链。

相反，如果底层数据库、文件系统或第三方 SDK 只是当前实现，包并不想承诺调用方依赖它的具体错误类型，那么直接用 %w 会把这个内部选择暴露出去。未来替换实现时，调用方可能已经依赖某个外部错误类型。此时可以用 %v 重新表达错误，或者定义自己的稳定哨兵值和自有错误类型，再只包装这层公共契约。

这几个细节最容易让错误判断失效

第一，%w 的对应参数必须是实现 error 接口的值；它不是“比 %v 更通用”的字符串占位符。第二，不要用 err == target 替代 errors.Is(err, target)，包装后错误值通常已经不是同一个对象。第三，类型判断不要靠字符串前缀，应该让自定义错误实现 Error 和必要的 Unwrap，再用 errors.As。第四，日志层可以把最终错误打印出来，但不要因为日志文本看起来正确，就误以为错误链仍然存在。

常见问题

%v 和 %w 打印出来一定完全一样吗？

在底层错误和格式模板相同的前提下，错误文本通常一致。区别在返回值是否保留可解包关系，而不是人眼看到的字符串。

所有 fmt.Errorf 都应该改成 %w 吗？

不应该。要先决定底层错误是否属于当前包愿意长期支持的 API。只需要日志上下文或需要隐藏实现细节时，%v 反而更合适。

为什么 errors.Is 还是匹配不到？

逐层检查包装链：中间是否有一层用了 %v，目标是否真的与返回链中的哨兵值相同，以及自定义错误是否实现了正确的 Unwrap 方法。

判断 %v 和 %w 时，先问“调用方是否需要程序化识别底层错误”，再问“这个底层错误是否值得公开”。文本可读只是第一层结果，错误链才决定后续代码能否稳定地做判断。