Go 错误处理机制详解：新手从 err != nil 到 errors.Is/As

刚开始学 Go 的时候，很多人都会被这段代码刷屏：

if err != nil { return err }

写多了以后，心里难免冒出一个问题：

为什么 Go 到处都要手动判断 err？ 为什么不像其他语言那样 try/catch？

这篇文章就从新手视角，把 Go 的错误处理机制讲清楚。

你会看到：

• error到底是什么

• 为什么 Go 推荐显式处理错误

• nil在错误处理中是什么意思

• 如何创建错误

• 如何给错误添加上下文

• 如何判断一个错误是不是某种错误

• 如何取出自定义错误里的字段

• panic和普通错误有什么区别

• 实战中怎样写出清晰的错误处理代码

先给一句核心结论：

Go 把错误当作普通值处理。

错误不是隐藏的异常控制流，而是函数返回值的一部分。你看得见它，也必须决定怎么处理它。

一、Go 的 error 是什么

在 Go 里，error是一个内置接口。

它可以理解成这样：

type error interface { Error() string }

只要一个类型实现了：

Error() string

它就可以作为error使用。

最简单的例子：

package main import ( "errors" "fmt" ) func divide(a, b int) (int, error) { if b == 0 { return 0, errors.New("division by zero") } return a / b, nil } func main() { result, err := divide(10, 0) if err != nil { fmt.Println("error:", err) return } fmt.Println("result:", result) }

输出：

error: division by zero

这里的函数返回两个值：

func divide(a, b int) (int, error)

第一个值是正常结果。

第二个值是错误。

如果没有错误，返回：

return result, nil

如果发生错误，返回：

return zeroValue, err

这里的zeroValue是对应类型的零值，例如：

• int的零值是0

• string的零值是""

• bool的零值是false

• 指针、slice、map、channel、interface 的零值是nil

二、为什么是 if err != nil

Go 的错误处理通常长这样：

value, err := doSomething() if err != nil { return err } // 只有没有错误时，才继续使用 value。

这不是模板代码的装饰，而是在表达一个很明确的流程：

调用函数 检查错误 如果有错误，处理或返回 如果没有错误，继续执行

Go 希望错误路径是显式的。

显式的好处是：

• 你能清楚看到每一步可能失败

• 你能在失败处补充上下文

• 你能决定是重试、忽略、返回、记录日志，还是终止程序

• 代码不会突然跳到远处的 catch 块

这也是 Go 风格里很重要的一点：

错误处理是正常业务流程的一部分。

三、nil 表示没有错误

在 Go 里，nil通常表示没有错误。

例如：

func save(name string) error { if name == "" { return errors.New("name is empty") } // 保存成功，没有错误。 return nil }

调用方这样判断：

err := save("alice") if err != nil { fmt.Println("save failed:", err) return } fmt.Println("save success")

这就是 Go 里最常见的错误处理模式。

新手可以先记住：

err == nil 表示成功 err != nil 表示失败

四、不要忽略错误

新手有时会这样写：

result, _ := divide(10, 0) fmt.Println(result)

这里的_表示丢弃错误。

这在语法上可以，但在业务上通常很危险。

如果你忽略错误，就等于告诉程序：

即使失败了，我也不关心。

但很多错误是必须处理的：

• 文件不存在

• 网络请求失败

• JSON 解析失败

• 数据库写入失败

• 参数不合法

• 权限不足

除非你非常确定这个错误可以忽略，否则不要随手写_。

更好的写法是：

result, err := divide(10, 0) if err != nil { fmt.Println("divide failed:", err) return } fmt.Println(result)

五、创建错误：errors.New

最简单的创建错误方式是errors.New。

package main import ( "errors" "fmt" ) func checkAge(age int) error { if age < 0 { return errors.New("age cannot be negative") } if age < 18 { return errors.New("age must be at least 18") } return nil } func main() { if err := checkAge(15); err != nil { fmt.Println("invalid age:", err) return } fmt.Println("age is valid") }

输出：

invalid age: age must be at least 18

errors.New适合创建固定文本的错误。

如果错误里要带变量，就更常用fmt.Errorf。

六、创建带变量的错误：fmt.Errorf

fmt.Errorf可以像fmt.Sprintf一样格式化错误信息。

package main import ( "fmt" ) func findUser(id int) error { if id <= 0 { return fmt.Errorf("invalid user id: %d", id) } return nil } func main() { if err := findUser(-1); err != nil { fmt.Println(err) } }

输出：

invalid user id: -1

相比：

errors.New("invalid user id")

fmt.Errorf可以把具体值放进去，让排查问题更方便。

七、错误信息应该怎么写

错误信息不是越长越好。

好的错误信息应该：

• 说明哪里失败

• 尽量带上关键上下文

• 不要首字母大写

• 不要以句号结尾

• 不要写成用户界面的提示语

例如：

return fmt.Errorf("open config %q: %w", path, err)

比下面这种更好：

return fmt.Errorf("Error! Something went wrong.")

Go 里错误常常会被一层层包装，最后组成一句完整信息。

例如：

load config "app.yaml": open file: permission denied

如果每一层都写成大写开头、感叹号、句号，最后就会很别扭。

八、添加上下文：不要只原样返回错误

假设你写了这样一个函数：

func loadConfig(path string) error { data, err := os.ReadFile(path) if err != nil { return err } _ = data return nil }

它能工作，但调用方看到错误时，可能只知道：

open config.yaml: no such file or directory

如果项目里有很多地方都读文件，就不容易知道这次失败发生在哪个业务步骤。

更推荐给错误加上下文：

func loadConfig(path string) error { data, err := os.ReadFile(path) if err != nil { return fmt.Errorf("read config %q: %w", path, err) } _ = data return nil }

注意这里用了%w。

fmt.Errorf("read config %q: %w", path, err)

%w表示包装一个错误。

包装以后：

• 错误信息会带上上下文

• 原始错误仍然可以被errors.Is或errors.As找到

完整例子：

package main import ( "fmt" "os" ) func loadConfig(path string) error { data, err := os.ReadFile(path) if err != nil { // %w 会包装原始错误，保留错误链。 return fmt.Errorf("read config %q: %w", path, err) } fmt.Println("config size:", len(data)) return nil } func main() { if err := loadConfig("missing.yaml"); err != nil { fmt.Println(err) } }

可能输出：

read config "missing.yaml": open missing.yaml: no such file or directory

这比单独返回底层错误更有用。

九、错误包装是什么

错误包装可以理解成：

在原始错误外面套一层上下文。

例如：

open missing.yaml: no such file or directory

被包装后变成：

read config "missing.yaml": open missing.yaml: no such file or directory

如果再往上包装：

start server: load app: read config "missing.yaml": open missing.yaml: no such file or directory

每一层都告诉你：

我在做什么的时候失败了。

这对排查问题很重要。

十、errors.Is：判断错误是不是某个错误

有时你不只想打印错误，而是想判断错误类型。

例如：

如果文件不存在，就创建默认配置。 如果是权限错误，就直接返回。

Go 推荐用errors.Is来判断错误链里是否包含某个目标错误。

package main import ( "errors" "fmt" "os" ) func loadConfig(path string) error { _, err := os.ReadFile(path) if err != nil { return fmt.Errorf("read config %q: %w", path, err) } return nil } func main() { err := loadConfig("missing.yaml") if err == nil { fmt.Println("config loaded") return } if errors.Is(err, os.ErrNotExist) { fmt.Println("config does not exist, use default config") return } fmt.Println("load config failed:", err) }

输出：

config does not exist, use default config

为什么不用字符串判断？

不要这样写：

if strings.Contains(err.Error(), "no such file") { // ... }

原因是：

• 错误文本可能变化

• 不同系统上的错误文本可能不同

• 字符串匹配容易误判

• 包装错误后文本更复杂

errors.Is是结构化判断，比字符串判断可靠。

十一、哨兵错误 sentinel error

哨兵错误是预先定义好的固定错误值。

例如：

var ErrNotFound = errors.New("not found")

调用方可以用errors.Is判断：

if errors.Is(err, ErrNotFound) { // 处理未找到 }

完整例子：

package main import ( "errors" "fmt" ) var ErrUserNotFound = errors.New("user not found") func findUserName(id int) (string, error) { if id == 100 { return "Alice", nil } return "", fmt.Errorf("find user %d: %w", id, ErrUserNotFound) } func main() { name, err := findUserName(200) if err != nil { if errors.Is(err, ErrUserNotFound) { fmt.Println("show empty user page") return } fmt.Println("find user failed:", err) return } fmt.Println("user:", name) }

输出：

show empty user page

哨兵错误适合表达稳定、可判断的错误状态。

常见例子：

• io.EOF

• os.ErrNotExist

• context.Canceled

• context.DeadlineExceeded

但不要给每一个错误都创建哨兵错误。

如果调用方不需要专门判断，就普通返回错误即可。

十二、errors.As：取出某种错误类型

errors.Is用来判断“是不是某个错误”。

errors.As用来判断“错误链里有没有某种错误类型”，并把它取出来。

例如你定义了一个带字段的错误类型：

type ValidationError struct { Field string Value string } func (e ValidationError) Error() string { return fmt.Sprintf("invalid %s: %q", e.Field, e.Value) }

调用方可能不只想知道“验证失败”，还想知道哪个字段失败。

完整例子：

package main import ( "errors" "fmt" ) type ValidationError struct { Field string Value string } func (e ValidationError) Error() string { return fmt.Sprintf("invalid %s: %q", e.Field, e.Value) } func validateName(name string) error { if name == "" { return ValidationError{ Field: "name", Value: name, } } return nil } func createUser(name string) error { if err := validateName(name); err != nil { return fmt.Errorf("create user: %w", err) } return nil } func main() { err := createUser("") if err == nil { fmt.Println("user created") return } var validationErr ValidationError if errors.As(err, &validationErr) { fmt.Println("field:", validationErr.Field) fmt.Println("value:", validationErr.Value) return } fmt.Println("create user failed:", err) }

输出：

field: name value:

注意errors.As的第二个参数：

errors.As(err, &validationErr)

这里要传目标变量的地址。

十三、自定义错误类型

当错误不只是一个字符串，而是需要携带结构化信息时，可以定义自己的错误类型。

例如：

package main import ( "fmt" "time" ) type RateLimitError struct { RetryAfter time.Duration } func (e RateLimitError) Error() string { return fmt.Sprintf("rate limited, retry after %s", e.RetryAfter) } func callAPI() error { return RateLimitError{ RetryAfter: 2 * time.Second, } } func main() { err := callAPI() if err != nil { fmt.Println(err) } }

输出：

rate limited, retry after 2s

自定义错误类型适合：

• 需要暴露错误分类

• 需要携带字段

• 调用方需要根据字段做不同处理

如果只是简单描述失败原因，errors.New或fmt.Errorf就够了。

十四、errors.Join：合并多个错误

有时一个操作可能同时产生多个错误。

例如关闭多个资源时，可能每个资源都关闭失败。

Go 的errors.Join可以把多个错误合并成一个错误。

package main import ( "errors" "fmt" ) func main() { err1 := errors.New("close file failed") err2 := errors.New("close network failed") err := errors.Join(err1, err2) if err != nil { fmt.Println(err) } }

可能输出：

close file failed close network failed

errors.Join会忽略 nil 错误。

如果传进去的错误全是 nil，它会返回 nil。

示例：

package main import ( "errors" "fmt" ) func main() { err := errors.Join(nil, nil) fmt.Println(err == nil) }

输出：

true

在新手阶段，你不一定经常用到errors.Join，但知道它可以表达“多个错误同时存在”就够了。

十五、defer 和错误处理

错误处理经常和defer一起出现。

defer用来注册函数结束前要执行的操作，常见于释放资源。

例如：

package main import ( "fmt" "os" ) func readFile(path string) error { file, err := os.Open(path) if err != nil { return fmt.Errorf("open file %q: %w", path, err) } defer file.Close() buffer := make([]byte, 16) _, err = file.Read(buffer) if err != nil { return fmt.Errorf("read file %q: %w", path, err) } return nil } func main() { tmp, err := os.CreateTemp("", "go-error-demo-*.txt") if err != nil { fmt.Println("create temp file:", err) return } defer os.Remove(tmp.Name()) if _, err := tmp.WriteString("hello go"); err != nil { fmt.Println("write temp file:", err) return } tmp.Close() if err := readFile(tmp.Name()); err != nil { fmt.Println("read failed:", err) return } fmt.Println("read success") }

输出：

read success

defer file.Close()的意思是：

不管 readFile 后面是成功返回，还是因为错误提前返回，都要关闭文件。

十六、关闭资源时的错误要不要处理

很多人会写：

defer file.Close()

这很常见，但有一个细节：

Close 本身也可能返回错误。

如果你写的是只读文件，忽略Close错误通常问题不大。

但如果你写文件，Close时可能才发现刷盘失败。这时最好处理关闭错误。

示例：

package main import ( "fmt" "os" ) func writeReport(path string, content string) (err error) { file, err := os.Create(path) if err != nil { return fmt.Errorf("create report %q: %w", path, err) } defer func() { closeErr := file.Close() if closeErr != nil && err == nil { err = fmt.Errorf("close report %q: %w", path, closeErr) } }() if _, err := file.WriteString(content); err != nil { return fmt.Errorf("write report %q: %w", path, err) } return nil } func main() { tmp, err := os.CreateTemp("", "report-*.txt") if err != nil { fmt.Println("create temp file:", err) return } path := tmp.Name() tmp.Close() defer os.Remove(path) if err := writeReport(path, "hello report"); err != nil { fmt.Println("write report failed:", err) return } fmt.Println("write report success") }

这里用了命名返回值：

func writeReport(path string, content string) (err error)

defer里可以看到即将返回的err，并在需要时补上关闭错误。

这个写法对新手来说稍微绕一点。先理解思路就好：

如果 Close 的错误很重要，就不要完全忽略它。

十七、panic 不是普通错误处理

Go 里还有panic。

panic会停止当前函数的正常执行，并开始展开调用栈。已经注册的defer会执行。

示例：

package main import "fmt" func main() { defer fmt.Println("defer runs") fmt.Println("before panic") panic("something is broken") }

输出大致会是：

before panic defer runs panic: something is broken

程序会异常退出。

那什么时候用panic？

新手可以先记住：

普通可预期错误用 error。 程序无法继续、违反内部不变量时，才考虑 panic。

例如：

• 用户输入错误：返回error

• 文件不存在：返回error

• 网络超时：返回error

• 配置格式错误：返回error

• 数组越界、空指针、不可恢复的内部状态：可能触发panic

不要把panic当成 try/catch 的替代品。

十八、recover：从 panic 中恢复

recover可以在defer函数中捕获 panic，让程序恢复控制。

示例：

package main import "fmt" func safeRun() { defer func() { if r := recover(); r != nil { fmt.Println("recovered:", r) } }() fmt.Println("before panic") panic("boom") } func main() { safeRun() fmt.Println("program continues") }

输出：

before panic recovered: boom program continues

recover只能在 deferred function 里直接调用才有效。

但是注意：

recover 不是让你随便吞掉所有 panic。

更常见的使用场景是：

• HTTP 服务器中间件兜底，避免单个请求导致整个服务退出

• goroutine 顶层保护，记录 panic 日志

• 框架边界把 panic 转成错误响应

业务逻辑里的普通失败，仍然应该返回error。

十九、把 panic 转成 error

有时你调用的代码可能 panic，但你希望函数对外返回error。

可以这样写：

package main import ( "fmt" ) func riskyDivide(a, b int) int { if b == 0 { panic("division by zero") } return a / b } func safeDivide(a, b int) (result int, err error) { defer func() { if r := recover(); r != nil { err = fmt.Errorf("safe divide failed: %v", r) } }() result = riskyDivide(a, b) return result, nil } func main() { result, err := safeDivide(10, 0) if err != nil { fmt.Println(err) return } fmt.Println(result) }

输出：

safe divide failed: division by zero

这类写法应该放在边界位置，不应该让整个项目都依赖 panic/recover 做普通流程控制。

二十、错误应该在哪里处理

当一个函数返回错误时，调用方有几种选择：

1. 直接处理

例如文件不存在时使用默认配置：

if errors.Is(err, os.ErrNotExist) { useDefaultConfig() return nil }

2. 添加上下文后继续返回

例如底层读文件失败，上层说明自己正在加载配置：

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

3. 转换成业务错误

例如数据库没找到用户，转换成业务层的ErrUserNotFound：

return fmt.Errorf("get profile: %w", ErrUserNotFound)

4. 记录日志并终止流程

例如main函数里：

if err := run(); err != nil { log.Fatal(err) }

新手最容易犯的错误是：每一层都打印日志，然后又继续返回错误。

例如：

if err != nil { log.Println(err) return err }

如果很多层都这么写，最后日志里会重复出现一堆相似错误。

更清楚的做法通常是：

底层返回错误 中间层添加上下文 最外层统一记录日志

二十一、实战例子：读取配置并处理错误

下面写一个稍微完整的例子。

需求：

读取配置文件。 如果文件不存在，使用默认配置。 如果文件为空，返回验证错误。 如果读取失败，保留底层错误。

完整代码：

package main import ( "errors" "fmt" "os" "strings" ) var ErrEmptyConfig = errors.New("empty config") type Config struct { AppName string } func parseConfig(content string) (Config, error) { content = strings.TrimSpace(content) if content == "" { return Config{}, ErrEmptyConfig } return Config{AppName: content}, nil } func loadConfig(path string) (Config, error) { data, err := os.ReadFile(path) if err != nil { return Config{}, fmt.Errorf("read config %q: %w", path, err) } config, err := parseConfig(string(data)) if err != nil { return Config{}, fmt.Errorf("parse config %q: %w", path, err) } return config, nil } func defaultConfig() Config { return Config{AppName: "demo-app"} } func main() { config, err := loadConfig("missing.conf") if err != nil { if errors.Is(err, os.ErrNotExist) { config = defaultConfig() fmt.Println("config file missing, use default config") fmt.Println("app name:", config.AppName) return } if errors.Is(err, ErrEmptyConfig) { fmt.Println("config file is empty") return } fmt.Println("load config failed:", err) return } fmt.Println("app name:", config.AppName) }

输出：

config file missing, use default config app name: demo-app

这个例子里有几个关键点：

1. parseConfig只负责解析，不负责读文件。

2. loadConfig给读文件和解析错误加上下文。

3. main决定怎么处理不同错误。

4. 判断错误时用errors.Is，而不是字符串匹配。

5. 文件不存在是可恢复错误，所以使用默认配置。

这就是比较典型的 Go 错误处理风格。

二十二、常见错误处理模式

早返回

Go 里很常见的写法是：

if err != nil { return err }

这叫早返回。

好处是：错误路径先处理，正常路径不用包在很深的else里。

不要写成：

if err == nil { // 一大段正常逻辑 } else { return err }

更推荐：

if err != nil { return err } // 一大段正常逻辑

包装后返回

跨函数返回错误时，给错误加上下文：

if err != nil { return fmt.Errorf("save user %d: %w", userID, err) }

判断特殊错误

使用errors.Is：

if errors.Is(err, os.ErrNotExist) { // 文件不存在 }

提取错误类型

使用errors.As：

var pathErr *os.PathError if errors.As(err, &pathErr) { fmt.Println("operation:", pathErr.Op) fmt.Println("path:", pathErr.Path) }

二十三、常见误区

误区一：用 panic 处理普通错误

错误写法：

if err != nil { panic(err) }

如果这是普通文件读取、网络请求、参数校验，就不应该 panic。

更好的写法：

if err != nil { return fmt.Errorf("read input: %w", err) }

误区二：错误信息没有上下文

不太好：

return err

更好：

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

当然也不是每一层都必须包装。关键是让最终错误信息能说明失败路径。

误区三：用字符串判断错误

不推荐：

if err.Error() == "not found" { // ... }

更推荐：

if errors.Is(err, ErrNotFound) { // ... }

误区四：吞掉错误

不推荐：

doSomething()

如果函数返回错误，应该接住：

if err := doSomething(); err != nil { return err }

误区五：重复打印同一个错误

底层打印一次，中间层打印一次，最外层又打印一次，会让日志变乱。

通常只在边界层记录日志，例如：

• main

• HTTP handler

• goroutine 顶层

• CLI 命令入口

中间层优先返回带上下文的错误。

二十四、新手错误处理检查清单

写 Go 代码时，可以用这张清单检查：

• 函数会失败吗？如果会，是否返回error？

• 调用函数后，是否检查了err != nil？

• 返回错误时，是否保留了原始错误？

• 需要跨层传递时，是否用%w包装？

• 判断错误时，是否使用errors.Is或errors.As？

• 是否避免了用字符串匹配错误？

• 是否只在真正异常的情况下使用panic？

• 打开文件、连接等资源后，是否用defer释放？

• 关闭资源的错误是否重要？如果重要，是否处理了？

• 日志是否只在合适的边界层打印？

二十五、学习路线建议

如果你是新手，可以按这个顺序练：

1. 写一个返回error的函数。

2. 用errors.New创建固定错误。

3. 用fmt.Errorf创建带变量的错误。

4. 用if err != nil做早返回。

5. 用%w包装错误。

6. 用errors.Is判断哨兵错误。

7. 定义一个自定义错误类型。

8. 用errors.As取出自定义错误。

9. 用defer释放资源。

10. 理解panic/recover，但不要滥用。

这些练顺以后，Go 的错误处理就不再只是“满屏 if err != nil”，而是一套很清晰的失败处理机制。

总结

Go 的错误处理可以压缩成几句话：

• error是一个接口，核心方法是Error() string。

• nil表示没有错误。

• 普通失败应该返回error，不要用panic。

• errors.New创建固定错误。

• fmt.Errorf创建格式化错误。

• %w用来包装错误，保留错误链。

• errors.Is用来判断错误链里是否有某个错误。

• errors.As用来取出错误链里的某种错误类型。

• errors.Join可以合并多个错误。

• defer常用于释放资源。

• recover只适合在边界位置处理 panic。

• 底层返回错误，中间层加上下文，边界层统一记录日志。

最后记住一句：

Go 的错误处理不是为了少写代码，而是为了让失败路径清楚可见。

当你能清楚回答“这个错误在哪里产生、在哪里补充上下文、在哪里被处理”，你就真正开始掌握 Go 的错误处理了。

参考资料

• Go Blog: Errors are values

• Go Blog: Working with Errors in Go 1.13

• Package errors

• Package fmt: Errorf

• Builtin package: error, panic, recover

• Go Blog: Defer, Panic, and Recover

• Effective Go: Errors