应使用 fmt.Errorf 的 %w 动词包装错误以保留原始错误并支持 errors.Is/As；仅在边界层一次包装，避免嵌套；多错误用 errors.Join 聚合；调试用 %+v 查看完整链，生产环境需脱敏。
用 fmt.Errorf 的 %w 动词包装错误
Go 1.13 引入了错误包装（error wrapping），核心是让错误能携带原始错误并支持 errors.Is 和 errors.As。关键不是拼字符串，而是用 %w 动词：
err := fmt.Errorf("failed to read config file: %w", os.Open("config.json"))这样既保留了原始 *os.PathError，又添加了语义上下文。如果误用 %s 或直接字符串拼接，原始错误就丢失了，errors.Unwrap 返回 nil，后续判断会失效。
避免在中间层重复调用 fmt.Errorf 包装已包装的错误
常见错误是层层叠加 fmt.Errorf，比如：
// ❌ 错误：嵌套过深，且可能重复包装
err := fmt.Errorf("service layer error: %w", fmt.Errorf("repo layer error: %w", db.QueryRow(...)))这会导致错误链冗长、难以定位根因。正确做法是只在**边界处**添加上下文（如 HTTP handler、CLI 命令入口），内部函数应直接返回原始错误或用 fmt.Errorf("xxx: %w", err) 一次包装。若不确定是否已被包装，可用 errors.Is(err, someTarget) 判断，而不是盲目再包。
用 errors.Join 合并多个错误（Go 1.20+）
当一个操作触发多个独立失败（如并发写多个文件），需聚合错误而非丢弃：
var errs []error
for _, path := range paths {
if err := os.WriteFile(path, data, 0644); err != nil {
errs = append(errs, fmt.Errorf("write %s: %w", path, err))
}
}
if len(errs) > 0 {
return errors.Join(errs...) // 返回一个实现了 error 接口的 multierror
}errors.Join 返回的错误可被 errors.Is / errors.As 正确解析各子错误，比手动拼接字符串或自定义结构更标准、更易测试。
调试时用 fmt.Printf("%+v", err) 查看完整错误链
%+v 是调试包装错误的必备技巧，它会展开整个错误链，显示每层的调用栈和消息：
err := fmt.Errorf("api timeout: %w", fmt.Errorf("http client failed: %w", context.DeadlineExceeded))
fmt.Printf("%+v\n", err)输出中会包含每一层的文件/行号。注意：生产日志中不要直接打 %+v，因为可能泄露敏感路径或内部状态；应提取关键信息（如用 errors.Unwrap 找最底层错误类型，再分类记录）。
实际项目里最容易被忽略的是「在哪一层加上下文」——不是每个 if err != nil 都要包，而是聚焦在跨域边界（HTTP → service → repo）、用户可见错误（如 CLI 输入校验失败）、或需要统一监控的故障点。过度包装反而模糊了错误源头。 
