应使用 fmt.Errorf 包装错误以添加调用上下文而不丢失原始错误，必须用 %w 动词确保错误链完整，避免冗余描述，并在无需新增语义时直接返回原始错误。
为什么要用 fmt.Errorf 包装错误而不是直接返回原始错误
go 中的错误是值，原始错误（比如 os.Open 返回的 *os.PathError）通常缺乏调用上下文。直接返回会让上层难以定位问题发生位置——你看到 "no such file or Directory"，但不知道是读配置、加载模板，还是打开日志文件失败。fmt.Errorf 的核心作用是在不丢失原始错误的前提下，叠加调用栈语义信息，为后续日志、调试或分类处理提供依据。
fmt.Errorf 的正确用法：必须用 %w 动词包装底层错误
从 Go 1.13 开始，%w 是唯一被 errors.Is 和 errors.As 识别的包装动词。漏写或误用 %v/%s 会导致错误链断裂，无法用标准库函数判断错误类型或提取原始错误。
- ✅ 正确：
fmt.Errorf("failed to parse config: %w", err) - ❌ 错误：
fmt.Errorf("failed to parse config: %v", err)（丢失包装） - ❌ 错误：
fmt.Errorf("failed to parse config: %s", err.Error())（彻底丢弃原错误类型和字段）
func loadConfig(path string) error { data, err := os.ReadFile(path) if err != nil { return fmt.Errorf("loadConfig: failed to read %q: %w", path, err) } // ... return nil }包装时避免重复堆砌无意义上下文
错误消息不是日志，不需要时间戳、函数名（编译器已记录）、冗余前缀。重点描述「做什么事时出了什么错」，保持简洁可读。过度包装反而干扰排查。
- ❌ 冗余：
fmt.Errorf("in loadConfig() at 2024-04-05T10:23:00Z: failed to open file %q: %w", path, err) - ✅ 清晰：
fmt.Errorf("open config file %q: %w", path, err) - ⚠️ 注意：如果上层已包装过一次，下层不要再加“failed to”这类泛化动词，避免变成“failed to failed to…”
什么时候不该用 fmt.Errorf 包装
不是所有错误都需要包装。以下情况建议直接返回原始错误：
立即学习“go语言免费学习笔记（深入）”；
- 函数职责就是透传错误（如中间件、代理函数），且不添加新语义
- 错误本身已含足够上下文（例如
http.Client.Do返回的*url.Error已带 URL 和操作名） - 你只是做类型断言或临时检查，没改变错误含义（如
if errors.Is(err, os.ErrNotExist) { ... }）
强行包装会让错误链变长、信息稀释，也增加 errors.Unwrap 深度，影响性能和可读性。