VSCode调试Ruby/Rails需用ruby-rdbg扩展并确保Ruby≥3.0；配置launch.json用bundle bin启动、禁用bootsnap和并发；断点失效优先检查加载时机与进程模型。
VSCode 调试 Ruby 和 Rails 项目不是开箱即用的，核心问题在于 Ruby 的调试器生态已从 ruby-debug-ide + debase 迁移到基于 debug gem 的现代方案（LSP 支持、断点稳定、支持 RBS 类型），而 VSCode 的 ruby-rdbg 扩展是目前唯一官方推荐、真正可用的路径。
确认 Ruby 版本与 debug gem 兼容性
Ruby 3.1+ 原生支持 debug，但 Rails 项目常需额外处理。Ruby 3.0 需手动安装 debug gem 并确保使用 bundle exec rdbg 启动；Ruby 2.7 及更早版本不支持，强行安装会报 undefined method `set_trace_func' 错误。
- 运行
ruby -v确认版本，若低于 3.0，请升级 Ruby 或改用其他 IDE（如 RubyMine） - 在项目根目录执行
bundle add debug --group=development,test，避免污染生产环境 - 检查
Gemfile.lock中是否含debug (>= 1.8.0)，旧版debug (1.5.x)在 Rails 7.1+ 下可能无法停住断点
配置 launch.json 启动 Rails server 调试
VSCode 默认不识别 rails server 为可调试进程，必须用 rdbg 包装器启动，并禁用 fork —— 否则子进程脱离调试器控制，断点完全失效。
- 在
.vscode/launch.json中添加配置，关键字段："type": "rdbg"、"name": "Rails server"、"request": "launch"、"cwd": "${workspaceFolder}"、"command": ["bin/rails", "server"]（非rails server，确保走 bundle bin） - 必须添加环境变量：
"env": {"RUBYOPT": "-Eutf-8"}，否则中文路径或参数可能触发ArgumentError: invalid byte sequence in UTF-8 - Rails 7 默认启用
bootsnap，它会缓存 require 路径，导致修改后断点位置错乱；调试时建议临时注释config/boot.rb中的require "bootsnap/setup"
在控制器/模型中设断点却不停住？检查这些点
常见现象是点击行号设了断点，但请求发出后无响应、控制台无暂停提示——这几乎全是加载时机或进程模型问题，不是扩展没装好。
- Rails 开发服务器默认启用多线程（
config.enable_reloading = true），但rdbg当前不支持多线程断点同步；在config/environments/development.rb中添加config.allow_concurrency = false - 使用
binding.break替代 UI 断点更可靠：在 controller action 第一行写binding.break，保存后刷新页面，VSCode 会自动捕获并跳转 - 若用
rails runner或 Rake task 调试，launch.json 中"command"应改为["bin/rails", "runner", "path/to/script.rb"]，且不能加--参数分隔符，否则rdbg解析失败
调试时无法查看实例变量或调用栈？别忽略 rdbg 控制台
VSCode 的 Variables 面板有时为空或显示
- 断点暂停后，在 VSCode 下方的 Debug Console 输入
pp @user或ls（pry-byebug风格命令仍可用） - 想看完整调用栈？输入
bt（backtrace），比面板里折叠的更全 - 若遇到
Remote debugging is disabled提示，说明你用了rdbg --open但没配"showDebuggerOutput": true，或防火墙拦截了 localhost:1234 端口
真正卡住的往往不是“怎么配”，而是 Ruby 版本、Rails 加载机制、rdbg 启动方式三者之间的隐式耦合——比如 Rails 7.1 的 zeitwerk 自动加载会在首次 require 时才绑定源码路径，断点设在未加载的文件里自然无效。动手前先跑通 rdbg -e 'p 1+1'，再进 Rails，顺序不能反。
