正确包装错误必须用%w动词，如fmt.Errorf("loading config: %w", err)；合并多错误用errors.Join而非%w拼接；defer中关闭资源需显式处理错误覆盖，避免静默丢失。
用 fmt.Errorf 带格式化字符串包装错误
最常见也最容易误用的方式是直接用 fmt.Errorf("failed to read config: %w", err)。注意必须用 %w 动词（不是 %s 或 %v），否则原始错误会被丢弃，无法用 errors.Is 或 errors.As 检查。
典型错误写法：fmt.Errorf("read failed: %v", err) —— 这会丢失错误链，errors.Unwrap 返回 nil，下游无法判断是否是 os.IsNotExist 等具体类型。
正确做法：
err := os.Open("config.json")
if err != nil {
return fmt.Errorf("loading config: %w", err)
}
用 errors.Join 合并多个错误（Go 1.20+）
当一个函数中触发多个独立失败（比如并发调用多个服务，部分失败），需要把它们聚合成一个错误返回时，errors.Join 是标准方案。它保留所有子错误的完整链，且支持递归 Unwrap。
立即学习“go语言免费学习笔记（深入）”；
注意点：
-
errors.Join(nil, err)返回err，安全；但errors.Join(err1, err2, nil)仍有效 - 不能用
fmt.Errorf("%w %w", e1, e2)替代 —— 这只拼字符串，不构成可展开的错误树 - 日志打印时默认只显示顶层消息，需用
fmt.Printf("%+v", err)查看完整嵌套结构
避免在中间层用 errors.Wrap（第三方库）
如果你项目已引入 github.com/pkg/errors，要注意：它的 Wrap 和标准库 fmt.Errorf(... %w) 行为不兼容。混合使用会导致 errors.Is 失效 —— 因为 pkg/errors 的 Is 实现不识别标准库的 causer 接口。
建议统一策略：
- 新项目直接用 Go 1.13+ 标准库
%w语法 - 老项目迁移时，逐个替换
errors.Wrap(err, "msg")→fmt.Errorf("msg: %w", err) - 不要同时 import
github.com/pkg/errors和依赖%w的逻辑
上下文透传要小心 defer 中的错误覆盖
常见陷阱：在 defer 里关闭资源时出错，却无意覆盖了主逻辑的错误。
func processFile(path string) error {
f, err := os.Open(path)
if err != nil {
return fmt.Errorf("open %s: %w", path, err)
}
defer func() {
// ❌ 错误：如果 Close 失败，会覆盖前面的 err
_ = f.Close()
}()
// ... 处理逻辑
return nil
}
正确写法是显式检查并组合：
defer func() {
if closeErr := f.Close(); closeErr != nil {
if err == nil {
err = fmt.Errorf("close %s: %w", path, closeErr)
} else {
err = fmt.Errorf("process %s: %w; close: %w", path, err, closeErr)
}
}
}()
更稳妥的做法是用 errors.Join（Go 1.20+）或封装辅助函数处理“主错误 + 清理错误”的合并逻辑。
错误上下文不是加得越多越好，关键路径上每层只加必要语义（比如“解析 YAML”“连接数据库”），避免堆砌无信息量的 “failed in handler” 这类描述。真正难调试的，往往是那个被 defer 静默吞掉的关闭错误。
