Go fmt.Errorf 的 %w 只能包装一个错误吗

可以，但要先看 Go 版本：从 Go 1.20 开始，fmt.Errorf 支持在同一次调用中出现多个 %w，返回的错误会保留多个可遍历分支。若项目仍要兼容 Go 1.19 或更早工具链，不要直接把这段写法当成兼容代码。

一句话判断：需要给多个底层错误加一层格式化上下文时用多个 %w；只是把若干独立错误合并起来时优先考虑 errors.Join。两者都应配合 errors.Is 或 errors.As 判断，不要解析错误字符串。

先看结论：Go 1.20 起 fmt.Errorf 可以包装多个错误

以前常见的写法是一条错误链：

return fmt.Errorf("load profile: %w", err)

Go 1.20 以后，同一条格式化消息可以关联两个底层错误：

package main

import (
    "errors"
    "fmt"
)

var (
    errConfig = errors.New("配置无效")
    errRemote = errors.New("远端校验失败")
)

func validate() error {
    // 两个 %w 都保留错误身份，调用方仍可用 errors.Is 判断。
    return fmt.Errorf("profile validation failed: %w; remote check failed: %w", errConfig, errRemote)
}

func main() {
    err := validate()
    fmt.Println(errors.Is(err, errConfig)) // true
    fmt.Println(errors.Is(err, errRemote)) // true
}

这不是把两个错误拼成一段普通文本，而是让返回值同时保存两个错误操作数。标准库会为单个 %w 提供 Unwrap() error，多个 %w 则提供 Unwrap() []error，所以错误结构从“单链”变成了“多分支”。

升级前后写法有什么差异

如果是从旧项目迁移，先看项目的最低 Go 版本，而不是只看开发机版本。go.mod、CI 使用的镜像和发布构建机都应同步确认。无法升级工具链时，继续使用单个 %w，或在边界层定义兼容的聚合错误类型，不要把多个 %w 混入旧版本路径。

为什么 errors.Is 和 errors.As 仍然能找到它们

多错误包装改变的是遍历形状，不是判断方式。errors.Is 会沿着错误树查找目标值，errors.As 会沿着同一棵树寻找目标类型：

type RemoteError struct {
    Code int
}

func (e *RemoteError) Error() string {
    return fmt.Sprintf("remote code %d", e.Code)
}

func example() error {
    remote := &RemoteError{Code: 503}
    // 用多 %w 保留配置错误与结构化远端错误。
    return fmt.Errorf("sync failed: %w; upstream: %w", errConfig, remote)
}

func inspect(err error) {
    // 不比较 Error() 文本，直接判断哨兵错误。
    if errors.Is(err, errConfig) {
        fmt.Println("需要检查配置")
    }

    var remote *RemoteError
    // As 可以在多分支中找到结构化错误类型。
    if errors.As(err, &remote) {
        fmt.Println("上游状态码", remote.Code)
    }
}

这里不要自己调用 Unwrap 后写递归逻辑，也不要假设只有一层。调用方只关心“是否包含某个原因”或“是否存在某种类型”，让标准库处理单错误链和多错误树即可。

在 fmt.Errorf 与 errors.Join 之间做迁移选择

两者都能组合错误，但表达意图不同。fmt.Errorf 适合“这次操作失败，并且失败原因来自 A 和 B”这样的带上下文消息；errors.Join 更适合收集多个独立检查结果，例如批量校验多个字段后统一返回。需要先格式化一段上下文，再组合多个原因时，也可以把两者分成清晰的层次。

func collect(errs ...error) error {
    // Join 会忽略 nil；全部为 nil 时返回 nil。
    return errors.Join(errs...)
}

func save() error {
    err := collect(errConfig, errRemote)
    if err != nil {
        // 外层只补充一次操作上下文，底层原因仍可被 Is/As 找到。
        return fmt.Errorf("save profile: %w", err)
    }
    return nil
}

回归检查清单

1. 确认 go.mod 的最低版本不低于代码使用的语言和标准库能力。
2. 在 CI、容器镜像和发布机上执行 go version，不要只检查本地 IDE。
3. 为每个底层错误写一个 errors.Is 或 errors.As 断言，覆盖多个分支。
4. 检查全是 nil 的 errors.Join 是否按预期返回 nil。
5. 保留错误上下文，但不要让监控或业务判断依赖完整错误字符串。

因此，fmt.Errorf 的 %w 并非永远只能出现一次：Go 1.20+ 已支持多个包装对象。真正需要迁移的是版本边界和判断测试，而不是把旧代码机械地把一个 %w 改成两个。

相关问题

多个 %w 会不会让 errors.Is 失效？

不会。Go 1.20+ 会遍历多分支错误，errors.Is 仍能匹配每个底层错误；调用方应继续使用它，而不是比较错误文本。

fmt.Errorf 和 errors.Join 必须二选一吗？

不必。前者更强调格式化上下文，后者更强调聚合结果；可以先用 errors.Join 收集原因，再用一个外层 fmt.Errorf 补充操作上下文。

参考资料：Go 1.20 Release Notes、fmt 包文档、errors 包文档。