一文读懂 pretty_backtrace 的 10 个配置项：从值截断长度到有效行数全解析

一文读懂 pretty_backtrace 的 10 个配置项：从值截断长度到有效行数全解析

【免费下载链接】pretty_backtracePretty your exception backtrace.项目地址: https://gitcode.com/gh_mirrors/pr/pretty_backtrace

调试 Ruby 程序时，又长又乱的异常堆栈常常让人头疼。pretty_backtrace 是一款专为 Ruby 开发者打造的异常堆栈美化工具，它能在堆栈中自动附加局部变量名与对应值，让报错信息一目了然。本文带你一文读懂 pretty_backtrace 的 10 个配置项，从值截断长度到有效行数，手把手教你调出最适合自己的调试体验。所有配置都定义在核心文件lib/pretty_backtrace.rb中，改动一处即可立刻生效。

什么是 pretty_backtrace：让异常堆栈从杂乱变清晰

在默认情况下，Ruby 抛出的异常只显示"文件名:行号:in 方法名"，变量值需要你手动打日志才能看到。而 pretty_backtrace 借助debug_inspector底层能力，在每一层堆栈帧后自动追加局部变量名和值，效果对比非常直观：

# 启用前：只能看到调用位置 test.rb:10:in `recursive': bottom of recursive (RuntimeError) # 启用后：每一层都附带了 n 和 str 的实时值 test.rb:10:in `recursive' (n = 0, str = "Hi 0!! Hi 0!! Hi 0...): bottom of recursive (RuntimeError) from test.rb:9:in `recursive' (n = 1, str = "Hi 1!! Hi 1!! Hi 1...)

它的配置方式非常灵活：既可以通过PrettyBacktrace::CONFIG哈希直接修改，也可以使用内置的 setter 方法。接下来，我们逐项拆解它的全部配置能力。

一分钟快速上手：安装并启用 pretty_backtrace

在 Gemfile 中加入一行依赖，然后执行bundle即可：

gem 'pretty_backtrace'

启用方式有两种：显式调用，或者直接 require 自动启用文件：

require 'pretty_backtrace' PrettyBacktrace.enable # 更省事：require 即自动启用 require 'pretty_backtrace/enable'

lib/pretty_backtrace/enable.rb内部其实就是一行PrettyBacktrace.enable，所以按需选择即可。启用后无需任何额外配置，就能看到美化后的堆栈。

10 个配置项速览：默认值与作用一目了然

配置项 1：truncate_length——单行模式下的值截断长度

这是最常见的需求：当局部变量的值特别长（比如拼接过的大字符串）时，全量输出会刷屏。truncate_length默认值为 20，超过该长度的值会被截断并追加省略号：

PrettyBacktrace::CONFIG[:truncate_length] = 50

调大它可以看到更完整的变量值，调小则让堆栈更紧凑，适合在日志量大的生产环境使用。

配置项 2：multi_line——多行模式开关

默认的单行模式适合快速扫读；而multi_line = true会切换为多行模式，每个堆栈帧独占多行，同时展示[FILE]源码块和[LOCAL VARIABLES]变量块，甚至用->精确指向出错的那一行代码：

PrettyBacktrace.multi_line = true

多行模式是深度排查问题时最强大的武器，代价是输出体积明显变大。

配置项 3：multi_line_truncate_length——多行模式的值截断长度

进入多行模式后，变量值的截断长度独立于单行模式，默认值为 60。也就是说，多行模式允许展示更长的值，避免关键信息过早被截掉：

PrettyBacktrace::CONFIG[:multi_line_truncate_length] = 120

如果你的变量里含有超长 SQL 或 JSON，把它调大非常实用。

配置项 4：multi_line_indent——多行模式的缩进宽度

多行模式下，[FILE]与[LOCAL VARIABLES]块默认缩进 10 个空格，让附加信息与堆栈主体区分开来。若你希望层级更明显或更紧凑，可以调整它：

PrettyBacktrace::CONFIG[:multi_line_indent] = 4

缩进越小，输出的横向宽度越小，在窄终端中阅读更友好。

配置项 5：effective_lines——控制有效行数，0 表示无限

默认情况下，pretty_backtrace 会处理完整堆栈。但递归或深层调用会生成大量堆栈帧，全部美化既耗时又刷屏。effective_lines可以限制参与美化的堆栈行数，默认值 0 表示无限：

# 只美化最近 5 层堆栈 PrettyBacktrace.effective_lines = 5

这在排查递归爆栈问题时格外好用——你通常只关心最靠近异常发生的几层。

配置项 6：file_contents——是否显示源码上下文

在多行模式下，每个堆栈帧默认会附上出错位置附近的源码片段，方便对照代码。若你只想看变量值、不想要源码，可以关闭它：

PrettyBacktrace::CONFIG[:file_contents] = false

需要说明的是，该开关只对多行模式生效，且要求源码文件确实存在于磁盘上。

配置项 7：file_contents_lines——源码上下文行数

源码片段默认取出错行前后各 2 行（即上下各file_contents_lines行）。如果你希望看到更完整的上下文，可以适当增大：

PrettyBacktrace::CONFIG[:file_contents_lines] = 5

注意该配置与truncate_length类似，只在多行模式下有意义。

配置项 8：disabled_exception_classes——忽略指定异常类

有些异常（比如业务上频繁抛出的自定义异常）你并不想看到美化堆栈，disabled_exception_classes就是为此设计的。它内部通过kind_of?判断异常类型：

PrettyBacktrace::CONFIG[:disabled_exception_classes] = { BusinessError => true }

命中该集合的异常会保持原始堆栈，避免干扰，也顺带省去不必要的性能开销。

配置项 9：enable 与 disable——全局开关的两种用法

除了进程级启用，enable还支持块语法，实现"局部生效"：只有块内抛出的异常会被美化，块外不受影响：

PrettyBacktrace.enable do # 这里的异常堆栈会被美化 end PrettyBacktrace.disable do # 这里的异常堆栈保持原样 end

这对于只对特定代码段做精细调试、又不想影响全局输出的场景非常合适。

配置项 10：setter 快捷方法——三种高频配置的简便写法

lib/pretty_backtrace.rb的末尾为最高频的三个配置提供了 setter 方法，比直接操作CONFIG哈希更简洁：

PrettyBacktrace.multi_line = true PrettyBacktrace.file_contents = false PrettyBacktrace.effective_lines = 10

它们分别等价于修改CONFIG[:multi_line]、CONFIG[:file_contents]和CONFIG[:effective_lines]，属于语法糖，选你顺手的方式即可。

配置项最佳实践：按场景快速选择

总结：从值截断长度到有效行数，配置全部掌握

pretty_backtrace 的全部配置都集中在lib/pretty_backtrace.rb中，总计 8 个哈希配置项加上enable、disable与 setter 快捷方法，构成了完整的可调体系。从控制变量值显示宽度的truncate_length，到决定堆栈处理深度的effective_lines，再到多行模式的源码上下文与缩进，每一项都能精准应对不同的调试场景。

现在，打开你的 Gemfile 装上 pretty_backtrace，动手体验一下这 10 个配置项带来的调试效率提升吧。遇到问题先看源码注释，改动配置后立刻生效，无需重启。

【免费下载链接】pretty_backtracePretty your exception backtrace.项目地址: https://gitcode.com/gh_mirrors/pr/pretty_backtrace