Go 接口 nil 的坑：为什么 interface 不等于 nil，以及如何正确处理

从一次 panic 说起：err 不为 nil 却真的“没错误”

很多 Go 程序员都遇到过这样一个诡异的现象：函数返回的 error 接口变量，明明在底层是一个 nil 指针，但拿 err != nil 去判断时，结果却是 true，然后在后续代码里访问该错误对象的方法时直接 panic。这还不是最迷惑的，更奇怪的是，在日志里打印这个 err，有时打出来的却是 <nil>，有时却直接崩掉。

Go 接口 nil 的坑：为什么 interface 不等于 nil，以及如何正确处理

比如一个很常见的自定义错误类型：

type MyError struct {
    Code int
    Msg  string
}

func (e *MyError) Error() string {
    return fmt.Sprintf("%d: %s", e.Code, e.Msg)
}

func doSomething() error {
    var err *MyError
    // 根据某些条件，没有给 err 赋值
    return err
}

func main() {
    if err := doSomething(); err != nil {
        // 这里进得来
        log.Println(err.Error()) // panic: runtime error: invalid memory address or nil pointer dereference
    }
}

如果你曾经在这种问题上排查了一下午，我想你已经深刻体会了什么叫“Go 接口不等于 nil”。这个问题的根源，在于 Go 的接口值并不像 *T 那样只有一个指针，它由“动态类型”和“动态值”两部分组成。只有这两部分都是 nil，接口本身才是 nil。

Go 接口的底层结构：类型和值两段式

在 Go 的运行时中，一个接口值实际上由两个字（word）组成。对于空接口 interface{}，它对应的是 runtime.eface：一个指向类型信息的指针和一个指向数据区域的指针。对于非空接口（比如 error），对应的是 runtime.iface，其中一个是 itab（携带方法表）、另一个是数据指针。

简化后可以这样理解：一个接口变量，本质上是一个“类型 + 值”的组合。当你写：

var i interface{}

此时 i 的两个字段都是 nil，所以 i == nil 成立。但当你写：

var p *int
var i interface{} = p

i 的类型字段变成了 *int，值字段是 nil。因此 i 本身不再是 nil——它的类型信息已经存在了。这就是“为什么 interface 不等于 nil”的底层答案。

一处常见的误区是，很多朋友以为 interface{} 可以像 void* 一样随意承接任何指针，然后在函数返回时误以为返回一个 nil 指针就等同于返回一个 nil 接口。实际并不是。

为什么 interface 不等于 nil：一个典型错误示范

让我们把问题再聚焦到一个具体场景：自定义错误类型的指针没有初始化就返回给 error 接口。

前面那个 doSomething 例子已经说明了问题。它的本质是：error 接口的动态类型是 *MyError，动态值是 nil。Go 在比较两个接口时，要求动态类型相同且动态值相等。nil 接口的动态类型是 nil，动态值也是 nil，所以一个持有 *MyError 动态类型的接口永远不可能和 nil 相等。

这种问题在什么时候最容易爆发？大概有两类场景：

统一错误返回：项目里为了让错误携带错误码，定义了 type AppError struct 且实现了 Error()，某些分支忘记初始化就返回。
抽象接口返回：比如 ORM、缓存库的 Get 返回 interface{} 和 error，内部查询不到时可能返回一个未赋值的指针变量。

在第一类场景中，调用方可能还会因为 err.Error() 直接 panic 而误以为业务逻辑异常，实际上却是接口判断出错。在第二类场景中，接口里可能是一个 nil 切片或 nil map，导致调用方误认为有数据。

如何正确判断接口是否为 nil

在讨论如何判断之前，我建议你重新审视自己的需求。

如果只是想判断“这个接口变量没有承载任何值”，那么直接用 i == nil 是最简单可靠的。但如果你需要判断“接口里装的是不是某个具体类型的零值”，问题就复杂一些。你必须知道这个具体类型是什么，然后对它做类型断言，例如：

if e, ok := err.(*MyError); ok && e == nil {
    // 返回了一个 *MyError 类型的 nil 指针
}

如果接口可以是任意类型，你可以用反射来统一处理。但反射不是银弹，因为它要求接口动态类型必须是可空类型（chan、func、interface、map、pointer、slice），否则 Value.IsNil() 会直接 panic。先判断 Kind 是一个稳妥的做法：

func IsNilInterface(i interface{}) bool {
    if i == nil {
        return true
    }
    v := reflect.ValueOf(i)
    switch v.Kind() {
    case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice:
        return v.IsNil()
    }
    return false
}

这个函数能从“物理上”判断接口所持有的值是否是一个 nil 的容器类型。但它也有一个明显的缺陷：性能比直接比较慢很多，而且如果接口里是普通的 struct 值，它返回 false，这在逻辑上是正确的——struct 本来就不是 nil。

方案对比：直接比较、类型断言、反射

为了让你在真实项目里快速决策，我把三种判断方式的差异整理成一个表：

判断方式	适用场景	局限性	性能建议
`i == nil`	判断接口从未被赋值	接口持有 nil 指针时会误判	无额外开销，首选
类型断言 `if v, ok := i.(*T); ok && v == nil`	已知接口可能携带的若干具体类型	需要枚举所有类型，类型增加时要改代码	开销较低，可接受
反射 `reflect.ValueOf(i).IsNil()`	需要兼容任意容器类型	类型不是可空类型会 panic；不能识别非容器类型的零值	反射较重，不适合热路径

如果你写的代码恰好处于高频调用路径，我建议你优先从设计上规避，而不是每次都用反射去兜底。反射能解决问题，但不应该成为日常防御编程的主力。

工程上如何避免这个坑：从源头设计

说了这么多，落到实际工程，我更推荐把问题堵在源头，而不是到处写判断函数。以下几点我觉得比较重要：

明确返回约定：当函数返回值是一个接口类型时，内部如果使用指针类型变量，那么返回时一定要先判空，再决定返回 nil 还是返回该指针。不要直接 return err。
避免用零值指针作为业务信号：比如 *User 为 nil 表示“没有找到”，这很容易导致接口层误判。可以用 (bool, *User, error) 或 (*User, error) 并返回 ErrNotFound 哨兵错误，而不是返回 (nil, nil)。
统一错误类型规范：项目中所有自定义错误类型，建议只在真正出错时创建并返回，不要定义“预声明”的 nil 错误变量。就算要定义，也要确保接口里存的是真正的 nil 接口。
重视 code review：这个坑非常隐蔽，靠测试不一定能完全覆盖。在 code review 时，要特别关注“返回接口类型”的函数，观察是否有把 nil 指针直接塞给接口变量。