Go语言错误日志带堆栈打印教程

本文深入解析了Go语言中错误日志堆栈打印的核心原理与实战要点：标准库errors.New不记录调用位置，而pkg/errors通过runtime.Callers捕获PC、文件和行号，使%+v能展开完整堆栈；文章系统梳理了新项目应统一使用pkg/errors.New或errors.Wrap、关键入口需用WithStack补全上下文、迁移时优先选用标准库errors.Is/As而非混用Unwrap/Cause以避免堆栈丢失，并指出fmt.Printf("%+v", err)失效的三大常见原因（二次包装、误用%v格式、JSON序列化丢帧）；最后坦诚指出Go 1.20+虽增强错误链支持，但pkg/errors在堆栈精度控制和可视化调试上仍有不可替代性，真正难点不在API切换，而在工程中每一处遗漏Wrap的error传递——它会让整条调用链的可观测性瞬间归零。

为什么 errors.New 打不出堆栈，而 pkg/errors 可以

因为 errors.New 只返回一个带字符串的 error 接口实现，不记录调用位置；pkg/errors 的 errors.New 和 errors.Wrap 会在创建时捕获 runtime.Callers，把 PC、文件名、行号存进结构体里。没有这步，%+v 就没法展开堆栈。

实操建议：

• 所有新错误创建统一用 pkg/errors.New 或 errors.Errorf，别混用标准库 errors.New
• 在关键入口（如 HTTP handler、CLI 命令执行点）用 errors.WithStack 包一层，避免漏掉顶层调用上下文
• 注意 errors.Wrap 是“包装已有 error”，不是“新建 error”——传入 nil 会 panic，得先判空

迁移时 errors.Cause 和 errors.Unwrap 怎么选

errors.Cause 是 pkg/errors 自己的解包逻辑，会一直往下找最内层非包装 error；errors.Unwrap 是 Go 1.13+ 标准库接口，只解一层。两者行为不等价，混用容易丢堆栈或误判类型。

实操建议：

• 升级到 Go 1.13+ 后，优先用标准库 errors.Is 和 errors.As 判断错误类型和值，它们兼容 pkg/errors 的包装结构
• 需要完整原始 error（比如查 SQL 错误码）时用 errors.Cause(err)；仅需检查是否为某类包装错误时，用 errors.As(err, &target)
• 别在日志里直接 fmt.Printf("%+v", errors.Unwrap(err)) —— 它只剥一层，%+v 又会把剩下的包装体再展开，堆栈重复显示

fmt.Printf("%+v", err) 不出堆栈？检查这三个地方

常见现象：明明用了 pkg/errors，但 %+v 输出还是没文件行号，只有字符串。问题通常不在打印本身，而在 error 构造或传递过程被“擦除”了。

实操建议：

• 确认 error 没被强制转成标准 error 接口后又用 errors.New 二次包装——比如 return errors.New(err.Error())，这会丢掉所有堆栈
• 检查是否用了 fmt.Sprintf("%v", err) 或 log.Print(err) —— 这些只调 Error() 方法，不会触发 %+v 的扩展格式，必须显式写 %+v
• 如果 error 经过 JSON 编码/解码（比如发到日志服务），pkg/errors 的堆栈字段不会自动序列化，得自己加 MarshalJSON 方法或换用 github.com/go-errors/errors

Go 1.20+ 迁移后要不要删掉 pkg/errors

可以删，但不是无痛切换。标准库 errors 和 fmt 在 1.20 已支持 %w 和多层 Unwrap，但缺失两个关键能力：Frame 级别的源码位置控制、以及 %+v 中按调用深度缩进显示堆栈。

实操建议：

• 纯内部服务、错误链不深、不依赖堆栈可视化调试的项目，可逐步替换为 fmt.Errorf("msg: %w", err) + errors.Is/As
• 仍需精确控制哪一层打堆栈（比如跳过中间工具函数），保留 pkg/errors 更省事；它的 Frame.Skip 参数比标准库灵活
• 注意 pkg/errors 已归档（archive），不再维护，长期项目建议用 github.com/ztrue/tracerr 或自己封装一层轻量 wrapper

真正麻烦的从来不是换函数名，而是那些散落在 if/else 分支里、没 Wrap 就直接 return 的 error，它们一旦漏掉，整条链就断了。

好了，本文到此结束，带大家了解了《Go语言错误日志带堆栈打印教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！