MultiError 是 hashicorp/go-multierr 提供的错误聚合工具，核心价值在于保留原始错误栈和支持增量追加；errors.Join 会丢失调用链，而 multierr.Append 默认保留完整堆栈。
MultiError 是什么，为什么不能直接用 errors.Join
它不是标准库的一部分，而是 hashicorp/go-multierr 提供的轻量级错误聚合工具，核心价值在于「保留原始错误栈」和「支持增量追加」。标准库 errors.Join（Go 1.20+）虽然也能合并多个错误，但会丢弃中间的调用链——尤其在多 goroutine 场景下，你根本看不出哪个子任务在哪一行失败了。multierr.Append 则默认保留每个错误的完整堆栈（只要原始错误是带栈的，比如用 fmt.Errorf("%w", err) 或 errors.New 包装过），这对调试批量任务至关重要。
怎么安全地在 goroutine 中累积错误
并发写入同一个 error 变量是危险的，multierr.Append 本身不保证并发安全。常见错误是直接在循环里这么写：
var resultErr error
for _, item := range items {
go func() {
if err := process(item); err != nil {
resultErr = multierr.Append(resultErr, err) // ⚠️ 竞态！
}
}()
}
正确做法是：每个 goroutine 自己攒错，最后用 multierr.Append 合并一次。或者更稳妥——用 channel 收集错误，主 goroutine 统一处理：
- 用
sync.WaitGroup控制生命周期，避免提前返回 - 每个 worker 向
chan error发送非 nil 错误，主 goroutine 从 channel 读取并调用multierr.Append - 注意 channel 容量或用带缓冲 channel，防止 sender 阻塞
- 别忘了关闭 channel 和 range 完毕后检查是否为空（空 channel 会得到 nil）
multierr.Append 和 multierr.Combine 的区别在哪
multierr.Append 是增量式、可变参数的，适合边执行边收集；multierr.Combine 是一次性合并切片，语义更明确但要求你先把所有错误准备好。关键差异在 nil 处理逻辑：
立即学习“go语言免费学习笔记（深入）”；
-
Append(a, b)：如果a是 nil，返回b；如果b是 nil，返回a；都非 nil 才真正合并 -
Combine([]error{a, b, c})：自动过滤掉所有 nil 元素，再合并剩余项 - 性能上没本质差别，但
Append在循环中反复调用时，每次都要做 nil 判断，而Combine一次过，更适合已知全量错误集合的场景 - 如果某个子任务返回
nil，用Append不影响结果；但若误把nil塞进Combine的切片里，它会安静地忽略——这点容易被当成“没报错”，其实只是被吞了
为什么有时候 multierr.ErrorOrNil 返回 nil，但你知道肯定有错
这是最常踩的坑：multierr.ErrorOrNil 只在传入的 error 是 multierr.Error 类型（或其子类型）且内部错误列表为空时才返回 nil；但它**不会递归展开嵌套的 multierr.Error**。比如你用 fmt.Errorf("wrap: %w", multierr.Append(e1, e2)) 包了一层，外层错误就不再是 multierr.Error，ErrorOrNil 就无法识别内层结构，直接返回那个 fmt.Errorf 实例（非 nil）。这时候该用 errors.Is 或 errors.As 检查底层是否含 multierr：
if merr, ok := errors.Cause(err).(interface{ Unwrap() []error }); ok {
// 手动展开
}
更现实的做法是：别依赖 ErrorOrNil 做判断，统一用 if err != nil，然后用 multierr.Format 或日志打印时调用 multierr.Error(err) 来展示全部细节。
真正麻烦的是错误链里混用了标准库 errors.Join 和 multierr——前者生成的错误无法被后者识别，展开逻辑断掉。一旦引入 multierr，整个错误处理链路最好保持一致，别中途切到 errors.Join。
