VSCode本身不运行Ruby，仅调用系统已安装的ruby命令；必须先确保集成终端中which ruby输出.rbenv/shims或.rvm/rubies路径、状态栏显示Ruby版本，再配置castwide.ruby-lsp插件、debug gem及匹配type为"ruby_lsp"的launch.json，且须从项目根目录执行code .启动。
VSCode 本身不运行 Ruby，它只是调用你系统里已装好的 ruby 命令。如果你在终端敲 ruby -v 都失败，那 VSCode 里点任何按钮都没用——所有后续配置都建立在错误前提上。
确认 ruby 和 bundle 在 VSCode 终端里能用
这是最常被跳过的一步，但 90% 的“点 ▶️ 没反应”“断点灰掉”“跳转失效”都卡在这儿。
- 在 VSCode 集成终端（
Ctrl + `）里执行which ruby和which bundle，输出路径必须含.rbenv/shims或.rvm/rubies，不能是/usr/bin/ruby - Mac 用户：把
rbenv init输出的eval行加进~/.zprofile（不是~/.zshrc），然后彻底退出 VSCode（Cmd + Q），再重开 - Windows 用户：RubyInstaller 安装时务必勾选 “Add Ruby executables to your PATH”，否则手动把
C:\Ruby32-x64\bin加进系统环境变量，重启 VSCode - 验证成功标志：状态栏左下角显示
Ruby 3.x.x，且gem list能列出已安装的 gem
launch.json 中 type 字段必须和实际插件匹配
写错 type 会导致调试器启动即退出、断点变灰、控制台报 undefined method `write' for nil:NilClass 这类诡异错误。
- 用
castwide.ruby-lsp插件（推荐）→"type": "ruby_lsp"，且删掉所有pathToRDebugIDE、rdebug-ide相关字段 - 用老插件
rebornix.ruby（不推荐，已停更）→"type": "Ruby"，但 Ruby ≥ 3.1 会崩溃 - Rails 项目调试服务器：
"program": "${workspaceFolder}/bin/rails"，不能写"rails"——后者不走bundle exec环境 - 调试单个脚本：
"program": "ruby ${file}"比"${file}"更稳，避免 shebang 或权限问题导致启动失败
调试必须用 debug gem，别碰 byebug 或 pry-byebug
byebug 在 Ruby 3.1+ 上已不可用，pry-byebug 会和 debug 冲突，导致断点卡死或进程假死。
- 在 Gemfile 里加：
gem "debug", group: :development, require: false，然后bundle install - 删干净所有
binding.pry、byebug、pry-byebug—— 它们和debug不共存 - Rails 7+ 项目：在
config/environments/development.rb加config.autoloader = :classic，再跑bin/rails tmp:clear，否则断点常跳错文件 - 如果断点仍不进
app/models，在launch.json的env字段加"RUBY_DEBUG_NO_RAILS": "1"，临时禁用 Rails 集成验证是否是 autoload 干扰
ruby-lsp gem 必须本地安装，且路径要对得上当前 Ruby 版本
castwide.ruby-lsp 插件只是前端壳，真正干活的是你本地装的 ruby-lsp 可执行文件。只装插件不装 gem，Output 面板里 “Ruby LSP” 标签页会一直卡在 Indexing 或报 Failed to start language server。
- 先确保当前终端 Ruby 版本和项目一致：
rbenv local 3.2.2（或rvm use 3.2.2），再运行gem install ruby-lsp -
ruby-lsp≥ 0.15 要求 Ruby ≥ 3.1；旧版 Ruby（如 2.7）装最新ruby-lsp会静默失败 - 项目用了 Bundler？在 VSCode 设置里把
rubyLsp.serverPath改成bundle exec ruby-lsp，否则 LSP 加载不到Gemfile.lock里的依赖 - 必须从项目根目录启动 VSCode：
code .，不能双击图标或用open -a—— 后者根本读不到rbenvshims
最容易被忽略的其实是启动方式：哪怕所有配置都对，用图形界面打开 VSCode，rbenv 和 GEM_PATH 就全丢了；code . 这个动作不是可选项，是必要条件。
