用 Byebug 调试 Ruby 应用：断点、单步与调用栈实战
还在用 puts 调试 Ruby？本文系统讲解 Byebug 的断点设置、变量检查、调用栈导航和单步执行命令，帮你快速定位复杂逻辑中的 bug。
Byebug 是 Ruby 2.x/3.x 的断点调试器，在代码里写一行 byebug 就能让程序停在该处，然后查看变量、单步执行、翻阅调用栈。它远比重启应用加打印语句高效，是排查复杂逻辑问题的标准工具。
为什么打印语句不够用
puts 调试的问题是：每改一处都要重启程序、输出淹没在日志里、只能看到你"想到要打印"的变量。调试器的思路相反——让程序停住，现场有什么就看什么，还能动态执行任意表达式验证猜想。
安装与基本用法
gem install byebug
Rails 项目把它加进 Gemfile 的 development 组即可。用法只需一行：
def calculate_total(items)
byebug
items.sum { |i| i.price * i.quantity }
end
程序执行到 byebug 会暂停并进入交互界面，提示符变成 (byebug)。
断点处的常用命令
查看变量与表达式：直接输入变量名或任意 Ruby 表达式，立即求值：
(byebug) items
(byebug) items.map(&:price)
(byebug) user&.admin?
var local：列出所有局部变量var instance：列出当前对象的实例变量pp complex_object：美化打印复杂结构
控制执行流程：
next（n）：执行下一行，不进入方法内部step（s）：单步进入方法内部finish：执行完当前方法并停在返回处continue（c）：继续运行直到下一个断点或程序结束
查看代码与调用栈：
list（l）：显示当前位置附近的源码backtrace（bt）：打印完整调用栈up/down：在调用栈帧间移动，查看上层调用者的变量状态frame N：直接跳到第 N 层栈帧
条件断点与动态断点
除了在源码里写死 byebug，还可以在调试会话中动态设置：
(byebug) break order.rb:42
(byebug) break Order#process if user.vip?
条件断点只在表达式为真时触发，排查循环里"第 500 次迭代才出错"这类问题时尤其好用。
在 Rails 与测试中使用
Rails 控制台和服务器都支持 byebug：开发模式下 rails server 启动后，请求处理到断点处会在终端挂起等待调试。RSpec 测试同理——在失败的用例里插入 byebug，运行测试即可停在案发现场。
远程或容器环境可以改用 byebug 的远程模式，或直接使用 Ruby 3.1+ 内置的 debug gem（binding.break），它原生支持 VS Code 断点联动。
常见问题（FAQ）
Q：Byebug 和 debug gem 选哪个？
Ruby 3.1 及以上推荐 debug gem（gem 'debug'），它是官方维护的新一代调试器，支持远程调试和编辑器集成；老项目或 Ruby 2.x 继续用 Byebug 没问题，两者命令高度相似。
Q：调试时不小心 next 过头了怎么办？
调试器不支持回退执行。习惯在关键分支前设断点而不是一路 next；真的错过了就重来一次——这也提醒你把可疑逻辑拆小，让单次调试会话更短。
Q：生产环境能用调试器吗？
不能也不该。生产问题靠日志、错误追踪和 APM 定位；调试器属于开发和测试环境。记得在提交流程里加检查，防止 byebug 语句被提交进主干。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
