Go error 判断为什么 errors.Is 返回 false

在 Go 里，errors.Is(err, target) 返回 false，通常不是 errors.Is 失效，而是 err 的错误链里根本没有可匹配的 target。最常见的两个原因是：上层用 %v 把底层错误只格式化成了文本，或者比较目标每次都用 errors.New 新建，导致它们不是同一个错误值。

排查时按“错误来源 → 包装方式 → 目标值”三层看即可：底层错误要用 %w 传递，哨兵错误要集中定义并复用，文本只用于展示，不能当作稳定的业务判断条件。

先把 errors.Is 的匹配范围看清楚

errors.Is 会先检查当前错误，再沿错误实现的 Unwrap() error 或 Unwrap() []error 继续查找。也就是说，它判断的是错误树中的值或自定义匹配规则，不是比较 Error() 返回的字符串。

下面这个最小例子同时保留了上下文和底层哨兵错误。代码中的注释只标出关键判断，不把每一行都机械翻译。

package main

import (
	"errors"
	"fmt"
)

var ErrStoreClosed = errors.New("store is closed")

func loadConfig() error {
	// %w 把 ErrStoreClosed 放进错误链，调用方才有机会继续匹配。
	return fmt.Errorf("load config: %w", ErrStoreClosed)
}

func main() {
	err := loadConfig()
	fmt.Println(err)
	fmt.Println(errors.Is(err, ErrStoreClosed))
}

load config: store is closed
true

先确认是不是把 %w 写成了 %v

fmt.Errorf 中的 %w 和 %v 都能把错误文字放进最终消息，但只有 %w 会建立可供 errors.Is 和 errors.As 遍历的包装关系。下面的两个返回值打印出来可能很像，判断结果却不同。

func keepChain() error {
	// %w 保留底层错误，适合需要让上层分类处理的边界。
	return fmt.Errorf("read profile: %w", ErrStoreClosed)
}

func flattenMessage() error {
	// %v 只拼接文字，返回值不再携带 ErrStoreClosed 的 Unwrap 关系。
	return fmt.Errorf("read profile: %v", ErrStoreClosed)
}

func compareWrapping() {
	fmt.Println(errors.Is(keepChain(), ErrStoreClosed))
	fmt.Println(errors.Is(flattenMessage(), ErrStoreClosed))
}

如果底层错误经过了日志格式化、字符串拼接或自定义错误类型，但没有提供 Unwrap() error，也会出现同样的现象。修复重点不是让上层重新解析文本，而是在错误刚被加上下文的位置恢复链路。

再检查目标是不是每次都由 errors.New 创建

errors.New("同一段文字") 每调用一次都会得到一个独立的错误值。errors.Is 默认按错误值相等或自定义 Is(error) bool 规则匹配，所以两次独立创建的同文错误不会因为文字相同而匹配。

func badTarget() bool {
	// 两次 errors.New 生成不同值，文字相同也不代表同一个哨兵错误。
	return errors.Is(errors.New("store is closed"), errors.New("store is closed"))
}

var ErrClosed = errors.New("store is closed")

func goodTarget() bool {
	// 生产者和调用者共享同一个包级哨兵值。
	return errors.Is(fmt.Errorf("open: %w", ErrClosed), ErrClosed)
}

业务错误建议在定义处集中声明，例如 var ErrNotFound = errors.New("not found")，调用方只依赖这个值；如果错误只用于展示，就不要再拿展示文本反向做控制流判断。

按错误链顺序处理多层包装和 errors.Join

真实项目中，一个错误可能先经过存储层、服务层和 HTTP 层多次包装。只要每层都使用 %w，最外层仍然可以匹配最底层的哨兵错误。不要因为消息前缀变了，就把判断改成字符串包含。

func repository() error {
	// 这一层只负责补充资源名，不改变可匹配的错误身份。
	return fmt.Errorf("repository: %w", ErrClosed)
}

func service() error {
	// 服务层继续包装，保留调用方所需的分类信息。
	return fmt.Errorf("load account: %w", repository())
}

func handle() string {
	if errors.Is(service(), ErrClosed) {
		// 命中哨兵值后返回稳定的业务分支。
		return "请稍后重试"
	}
	return "未知错误"
}

如果使用 errors.Join 聚合多个失败原因，返回错误会通过 Unwrap() []error 暴露一棵错误树，errors.Is 可以分别匹配其中的成员。需要注意的是，直接调用 errors.Unwrap 只处理返回单个 error 的 Unwrap 方法，不会替你展开 Join 的多错误结果。

func validate() error {
	// Join 允许一次返回多个独立原因，调用方仍按哨兵值分别判断。
	return errors.Join(ErrClosed, errors.New("missing region"))
}

func checkJoined() bool {
	return errors.Is(validate(), ErrClosed)
}

自定义 Is 方法只做浅层匹配

如果自定义错误类型需要表达“它等价于某个公开哨兵错误”，可以实现 Is(error) bool。这个方法应该只比较当前错误和目标，不要在里面递归调用 errors.Is 或手动执行 Unwrap，否则容易造成重复遍历或语义混乱。

import "io/fs"

type PermissionError struct {
	Operation string
}

func (e PermissionError) Error() string {
	return e.Operation + ": permission denied"
}

func (e PermissionError) Is(target error) bool {
	// 只声明当前类型与公开哨兵的等价关系，不深入遍历其他错误。
	return target == fs.ErrPermission
}

如果只是普通的上下文包装，不需要自定义 Is，优先使用 fmt.Errorf("...: %w", err)。自定义匹配属于公开契约的一部分，应该有稳定的目标值和清晰的文档。

常见误区与推荐修复

修复一个 errors.Is 问题时，可以固定执行这三个动作：沿返回路径找到最早产生错误的地方；逐层确认包装是否使用 %w 或提供了 Unwrap；最后确认调用方传入的是同一个哨兵值、可比较目标或有意设计的自定义匹配。

速查：errors.Is 返回 false 时看哪里

• 先看目标错误是否真的出现在返回链中，不要只看最终打印文本。
• 检查每个上下文层是否把 %w 误写成 %v。
• 检查目标是不是在调用点重新执行了 errors.New。
• 检查自定义错误是否实现了预期的 Is(error) bool。
• 遇到 errors.Join 时按错误树思考，不要只调用单错误形式的 errors.Unwrap。

最后，错误文本可以继续用于日志和用户提示，但错误分类应依赖错误链、哨兵值或类型。这样上层既能保留“读取配置失败”这类上下文，也能稳定判断底层究竟是关闭、未找到还是权限不足。

相关问题

为什么 errors.Is 比 err == target 更适合包装错误？因为它会沿 Unwrap 错误树查找，外层加了上下文后仍能命中目标。

%w 可以在一条 fmt.Errorf 中使用多次吗？写作时应按当前 Go 版本和项目约定确认具体格式，通常一个明确的底层错误链已经足够；需要聚合多个独立原因时使用 errors.Join 更直观。

能不能用 strings.Contains(err.Error(), "closed")？可以用于日志分析或临时诊断，但不建议作为稳定业务分支，因为文案一改就会改变控制流。