Go 错误处理完全指南：从 error 接口到 errors 包、panic/recover 与最佳实践
JetBrains 官方博客发表技术文章，由社区贡献者 Christoph Berger 撰写，系统讲解了 Go 语言的错误处理机制。文章在 2026 年 8 月进行了更新，反映了 Go 语言的最新变化。错误处理是 Go 与 Java、C++、JavaScript、Python 等主流语言差异最大的方面之一：在 Go 中，错误是值（errors are values），错误处理是程序流程的自然组成部分，而不是像异常那样被移出正常代码流程。文章涵盖了错误处理的基本技术、特定类型错误的处理方法、常见错误和最佳实践。
Go 错误处理的核心理念
错误是值
Go 错误处理的核心原则是"错误是值"（errors are values）。这意味着：
- 错误可以像其他值一样被赋值、传递、比较
- 错误处理是显式的，调用者必须检查返回的错误
- 错误不会像异常那样自动中断程序流程
- 开发者可以完全控制错误的处理方式
典型的 Go 错误处理模式：
result, err := someFunction()
if err != nil {
// 处理错误
return err
}
// 使用 result
为什么 Go 选择这种方式
Go 的设计者选择显式错误处理而非异常，是因为：
- 显式错误处理让代码更清晰，错误处理路径一目了然
- 避免了异常导致的隐式控制流跳转
- 鼓励开发者认真处理每一个可能的错误
- 减少了 try/catch/finally 带来的代码复杂度
- 错误作为值可以被灵活地包装、传递和组合
error 接口
定义
Go 的内置 error 接口定义非常简单：
type error interface {
Error() string
}
任何实现了 Error() string 方法的类型都满足 error 接口，可以作为错误使用。
自定义错误类型
开发者可以定义自己的错误类型：
type MyError struct {
Code int
Message string
}
func (e *MyError) Error() string {
return fmt.Sprintf("code %d: %s", e.Code, e.Message)
}
自定义错误类型可以携带额外的上下文信息，便于错误处理和调试。
errors 包
errors.New
创建简单错误：
err := errors.New("something went wrong")
errors.New 返回一个包含给定消息的错误值。适用于不需要额外上下文的简单错误。
errors.Is
判断错误是否匹配特定错误：
var ErrNotFound = errors.New("not found")
if errors.Is(err, ErrNotFound) {
// 处理未找到错误
}
errors.Is 会遍历错误链，检查是否有任何错误匹配目标错误。这对于包装错误后的判断非常重要。
errors.As
提取特定类型的错误：
var myErr *MyError
if errors.As(err, &myErr) {
// 使用 myErr.Code, myErr.Message
}
errors.As 会遍历错误链，找到第一个匹配目标类型的错误，并将其赋值给目标变量。
errors.Join（Go 1.20+）
组合多个错误：
err1 := errors.New("error 1")
err2 := errors.New("error 2")
combined := errors.Join(err1, err2)
errors.Join 将多个错误组合成一个错误，适用于需要报告多个错误的场景（如批量操作中的部分失败）。
errors.Unwrap
解包错误：
wrapped := fmt.Errorf("context: %w", originalErr)
unwrapped := errors.Unwrap(wrapped) // 返回 originalErr
errors.Unwrap 返回被包装的原始错误。errors.Is 和 errors.As 内部都使用了类似的解包逻辑。
fmt.Errorf 与错误包装
%w 动词
使用 fmt.Errorf 和 %w 动词包装错误：
originalErr := errors.New("original error")
wrappedErr := fmt.Errorf("failed to process: %w", originalErr)
%w 会将原始错误包装在新错误中，同时保留错误链。被包装的错误可以通过 errors.Is、errors.As 和 errors.Unwrap 访问。
%v 与 %w 的区别
%v：只将错误的字符串表示嵌入消息，不保留错误链%w：保留错误链，支持errors.Is和errors.As
建议在需要保留错误链时使用 %w，在只需要附加消息时使用 %v。
包装的最佳实践
- 在错误消息中添加上下文信息（操作名、资源标识等）
- 使用
%w保留原始错误，便于上层判断和处理 - 不要重复包装同一个错误
- 保持错误消息清晰、有意义
特定类型错误的处理
I/O 错误
I/O 操作（文件读写、网络通信）经常返回错误：
file, err := os.Open("data.txt")
if err != nil {
if errors.Is(err, os.ErrNotExist) {
log.Println("文件不存在")
} else if errors.Is(err, os.ErrPermission) {
log.Println("权限不足")
} else {
log.Printf("打开文件失败: %v", err)
}
return
}
defer file.Close()
常见的 I/O 错误包括：
os.ErrNotExist：文件不存在os.ErrPermission：权限不足os.ErrClosed：文件已关闭io.EOF：到达文件末尾io.ErrUnexpectedEOF：意外的文件结束
网络错误
网络操作的错误处理需要特别关注超时和临时错误：
conn, err := net.DialTimeout("tcp", "example.com:80", 5*time.Second)
if err != nil {
var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
log.Println("连接超时")
} else if errors.As(err, &netErr) && netErr.Temporary() {
log.Println("临时错误，可以重试")
} else {
log.Printf("连接失败: %v", err)
}
return
}
数据验证错误
输入验证错误通常需要向调用者提供详细信息：
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("validation error in %s: %s", e.Field, e.Message)
}
func validateUser(u *User) error {
if u.Name == "" {
return &ValidationError{Field: "name", Message: "name is required"}
}
if u.Age < 0 {
return &ValidationError{Field: "age", Message: "age must be non-negative"}
}
return nil
}
并发错误
在并发编程中，多个 goroutine 可能同时产生错误：
var wg sync.WaitGroup
var mu sync.Mutex
var errs []error
for _, task := range tasks {
wg.Add(1)
go func(t Task) {
defer wg.Done()
if err := t.Execute(); err != nil {
mu.Lock()
errs = append(errs, err)
mu.Unlock()
}
}(task)
}
wg.Wait()
if len(errs) > 0 {
return errors.Join(errs...)
}
Go 1.20+ 的 errors.Join 非常适合组合并发错误。
panic 和 recover
什么时候用 panic
在 Go 中，panic 应该用于真正不可恢复的错误：
- 程序初始化失败（如必需的配置文件缺失）
- 不可恢复的内部状态损坏
- 开发者错误（如数组越界、nil 指针解引用）
不应该用 panic 处理普通的可恢复错误（如 I/O 错误、网络错误、用户输入错误）。
panic 的行为
当 panic 被调用时：
- 当前函数立即停止执行
- 开始执行该函数中的
defer语句 - panic 传播到调用者，重复上述过程
- 如果没有被
recover，程序崩溃并输出堆栈跟踪
recover 的使用
recover 只能在 defer 函数中调用，用于捕获 panic：
func safeFunction() {
defer func() {
if r := recover(); r != nil {
log.Printf("recovered from panic: %v", r)
}
}()
// 可能 panic 的代码
}
recover 的最佳实践：
- 只在必要时使用，不要滥用
- 在 recover 中记录详细的日志和堆栈信息
- 考虑是否真的应该恢复，还是应该让程序崩溃
- 在库代码中避免 recover，让调用者决定如何处理
常见错误和陷阱
1. 忽略错误
// 错误：忽略错误
result, _ := someFunction()
// 正确：检查错误
result, err := someFunction()
if err != nil {
return err
}
忽略错误是 Go 代码中最常见的问题之一。即使你认为错误不可能发生，也应该至少记录日志。
2. 错误消息不清晰
// 错误：消息没有上下文
return errors.New("error")
// 正确：消息包含上下文
return fmt.Errorf("failed to read config file %s: %w", path, err)
好的错误消息应该包含：发生了什么操作、涉及什么资源、原始错误是什么。
3. 重复包装
// 错误：重复包装
err := fmt.Errorf("step1: %w", originalErr)
err = fmt.Errorf("step2: %w", err)
err = fmt.Errorf("step3: %w", err)
// 正确：在合适的层级包装
err := doStep1()
if err != nil {
return fmt.Errorf("step1 failed: %w", err)
}
过度包装会让错误链变得冗长，难以阅读。只在需要添加上下文时包装。
4. 不检查特定错误类型
// 错误：只检查 err != nil
if err != nil {
return err
}
// 正确：检查特定错误类型
if errors.Is(err, os.ErrNotExist) {
// 创建文件
} else if err != nil {
return err
}
不同的错误可能需要不同的处理方式。使用 errors.Is 和 errors.As 判断特定错误。
5. 在循环中 defer
// 错误：在循环中 defer，资源不会及时释放
for _, file := range files {
f, err := os.Open(file)
if err != nil {
return err
}
defer f.Close() // 直到函数返回才执行
// 处理文件
}
// 正确：在循环内使用闭包或手动关闭
for _, file := range files {
func() {
f, err := os.Open(file)
if err != nil {
log.Println(err)
return
}
defer f.Close() // 闭包结束时执行
// 处理文件
}()
}
最佳实践总结
- 始终检查错误：不要忽略任何返回的错误
- 添加上下文：使用
fmt.Errorf和%w包装错误，添加有意义的上下文 - 使用 errors.Is/As：判断特定错误时使用
errors.Is和errors.As，而不是字符串比较 - 保持错误消息清晰：错误消息应该说明发生了什么、为什么发生、涉及什么资源
- 合理使用 panic：只在不可恢复的错误时使用 panic，普通错误用 error 返回
- 避免过度包装：只在需要添加上下文时包装错误，不要重复包装
- 处理并发错误：使用
errors.Join组合多个 goroutine 的错误 - 记录详细日志：在处理错误时记录足够的上下文信息，便于调试
- 考虑错误的可恢复性：判断错误是否可恢复，决定是重试、返回还是终止
- 编写错误处理测试：测试各种错误场景，确保错误处理逻辑正确
总结
Go 的错误处理机制是其语言设计的核心特征之一。与基于异常的语言不同，Go 将错误作为一等公民，通过显式的 if err != nil 检查让错误处理路径清晰可见。error 接口的简洁设计、errors 包提供的 Is/As/Join/Unwrap 函数、fmt.Errorf 的 %w 包装机制，共同构成了 Go 强大而灵活的错误处理体系。panic 和 recover 则用于处理真正不可恢复的错误。掌握 Go 的错误处理需要理解"错误是值"的核心理念，熟悉 errors 包的使用，了解特定类型错误（I/O、网络、验证、并发）的处理方法，并避免常见的陷阱（忽略错误、消息不清晰、重复包装、不检查特定错误类型等）。遵循最佳实践，可以写出清晰、健壮、易于调试的 Go 代码。
来源：https://blog.jetbrains.com/go/2026/09/02/how-to-handle-errors-in-go/