Go 返回 typed nil error 为什么 err 不等于 nil

在 Go 里，函数明明“没有错误”，调用方却发现 err != nil，最常见的原因就是返回了 typed nil：底层指针的值是 nil，但它被装进 error 接口后，接口仍然携带具体动态类型。接口本身并不是 nil，所以比较结果为真。

修复重点不是把调用处的判断改复杂，而是让无错误分支直接返回真正的 nil；如果需要返回自定义错误，则只在确实有错误对象时返回它。

err == nil 比较的是接口是否为空

可以把 error 想成一个包含两部分的接口值：动态类型和动态值。真正的 nil 接口两部分都为空；而 typed nil 通常是“动态类型为 *MyError，动态值为 nil”。因此，下面两种状态并不相同：

Go 规范对接口比较的描述是：两个接口值只有在动态类型相同且动态值相等，或两者都为 nil 时才相等。因此，不能只看接口内部指针是不是 nil，就把整个接口当成 nil。

参考规范：https://go.dev/ref/spec#Comparison

哪种写法会制造 typed nil error

问题通常发生在函数声明返回 error，但局部变量却是某个错误指针类型时：

package main

import "fmt"

type MyError struct {
	Code int
}

// Error 让 *MyError 满足 error 接口。
func (e *MyError) Error() string {
	// 这里只读取错误字段；调用方仍应只在错误对象非 nil 时访问它。
	if e == nil {
		return "没有具体错误对象"
	}
	return fmt.Sprintf("业务错误：%d", e.Code)
}

func load() error {
	var detail *MyError
	// detail 的指针值是 nil，但返回到 error 后会保留 *MyError 动态类型。
	return detail
}

func main() {
	err := load()
	// 输出 false，因为 err 不是一个两部分都为空的 nil 接口。
	fmt.Println(err == nil)
	// %T 用来查看接口当前携带的动态类型。
	fmt.Printf("类型=%T，值=%v\n", err, err)
}

这里的关键不是 Error 方法是否能处理 nil 接收者，而是 return detail 发生了接口赋值。只要具体类型实现了 error，赋值过程就可能把 nil 指针和它的动态类型一起放入接口。

无错误时应该怎样返回

最直接的修复是让成功分支返回字面量 nil，不要返回一个值为 nil 的错误指针：

func load() error {
	var detail *MyError
	if hasProblem() {
		// 只有已经创建出具体错误时，才把它作为 error 返回。
		detail = &MyError{Code: 1001}
		return detail
	}
	// 成功分支返回真正的 nil 接口。
	return nil
}

func hasProblem() bool {
	// 示例只表达返回分支，实际项目中应替换为业务判断。
	return false
}

如果函数需要保留自定义错误类型，可以让它返回一个具体的非接口结果，再由调用方在明确的错误分支中转换；但对常规 func (...) error API 来说，成功分支使用 return nil 最清晰。

不要用“调用方发现 err != nil 后，再通过反射把它当成 nil”来掩盖返回逻辑。这样会让每个调用点都承担额外规则，日志、重试和错误包装也容易出现不一致。

怎么排查已经出现的 typed nil

排查时先打印动态类型，再回到返回路径检查接口赋值的位置：

func report(err error) {
	// %T 只观察动态类型，不会把 typed nil 自动转换成真正的 nil。
	fmt.Printf("error type=%T, error value=%v\n", err, err)
	if err == nil {
		return
	}
	// 进入这里后，仍要把 err 当作一个非 nil 接口处理。
	writeErrorLog(err)
}

func writeErrorLog(err error) {
	// 统一记录错误文本，避免在未知类型上直接解引用。
	fmt.Println(err.Error())
}

如果必须对特定指针错误做诊断，可以先做类型断言，再判断断言结果：

if err != nil {
	if detail, ok := err.(*MyError); ok {
		// detail 可能仍是 nil，类型断言成功不等于指针非 nil。
		if detail == nil {
			fmt.Println("发现 typed nil error")
		}
	}
}

这段判断适合定位遗留代码，不适合作为所有调用方的常规模板。errors.Is、errors.As 解决的是错误链匹配和类型提取，也不会把一个携带动态类型的 nil 接口改造成真正的 nil；根治仍然要回到返回函数。

常见问题

为什么打印出来像 nil，判断却是 false？

格式化输出通常只展示动态值，而 == nil 比较的是整个接口值。typed nil 的动态值可以显示为 ，但动态类型仍然存在。

给 Error 方法加 nil 接收者判断能修好吗？

不能。它只能避免某些 Error 方法内部解引用 nil 指针，不能改变接口已经携带动态类型这一事实。

最应该记住哪条规则？

返回类型是 error 时，成功分支写 return nil；返回自定义错误时，先确保指针确实指向一个错误对象。