VSCode 不自带 Ruby 环境，需手动配置 ruby 命令、ruby-lsp 和 debug gem；macOS 改 ~/.zprofile、Windows 加 PATH；禁用 Solargraph 等冲突插件；状态栏显示 Ruby 版本才是环境生效的唯一标志。
VSCode 本身不运行 Ruby，也不自带 Ruby 解释器或调试器——你点右上角 ▶️ 或按 F5 能不能跑起来，完全取决于终端里 ruby 命令是否可用、bundle exec 是否对齐项目依赖、以及调试器 gem 是否装在当前 Ruby 版本下。
which ruby 在 VSCode 终端里没输出？先修环境，别装插件
这是 90% 的“点不动”“跳转失效”“断点灰掉”的根源。VSCode 启动时读取的是图形界面的初始环境，不是你 iTerm / Terminal 里那个已配置好 rbenv/rvm 的 shell。
- macOS 用户：检查
~/.zprofile（不是~/.zshrc）是否包含eval "$(rbenv init - zsh)"；改完后必须 完全退出 VSCode（Cmd+Q）再重开 - Windows 用户：RubyInstaller 安装时务必勾选 “Add Ruby executables to your PATH”；若已安装未勾选，需手动把
C:\Ruby32-x64\bin加进系统环境变量，再重启 VSCode - 验证方式：在 VSCode 集成终端（Ctrl+`）中执行
which ruby（macOS/Linux）或where ruby（Windows），输出路径必须含.rbenv/shims、.rvm/rubies或Ruby32-x64\bin，不能是/usr/bin/ruby
ruby-lsp 必须本地装，只装插件没用
目前唯一活跃维护、支持 Ruby 3.2+ 新语法（如 then、参数解构、RBS 类型推导）的语言服务器是 ruby-lsp，它不是 VSCode 插件自带的，而是要你在项目里手动 gem install ruby-lsp。
- 如果用
rbenv，先rbenv local 3.2.2切到项目对应版本，再gem install ruby-lsp - 项目有
Gemfile且锁定了ruby-lsp？在 VSCode 设置里把rubyLsp.serverPath改成bundle exec ruby-lsp - 旧版 Ruby（如 2.6 以下）不兼容最新
ruby-lsp，会静默失败；打开 Output → “Ruby LSP” 面板，看到Failed to start language server就是这个原因 - 禁用所有 Solargraph 相关扩展（
castwide.solargraph已停更），二者不能共存
调试必须配 launch.json，且用 debug gem
Ruby 3.1+ 彻底移除了 debugger 方法，ruby-debug-ide 和 byebug 全部失效——F5 启动即退出、断点变灰、报 undefined method `write' for nil:NilClass，基本都是这个原因。
- 在
Gemfile的development组加gem 'debug'，然后bundle install - Cmd+Shift+P → “Debug: Open launch.json” → 选择 “Ruby”，生成基础配置；关键字段不能少：
"type": "Ruby"、"request": "launch"、"program": "${file}" - 不要碰
ruby.interpreterPath，它已废弃；VSCode 调试器只认当前终端环境下的ruby和bundle - 如果你常跑 Rails，
program可设为"${workspaceFolder}/bin/rails"并加"args": ["server"]
只留三个扩展：wingrunr21.vscode-ruby + ruby-rubocop + （可选）shawncarter.rails-run-specs
VSCode 插件市场搜 “ruby” 出来的二十多个扩展里，绝大多数冲突、停更或功能重叠。装多了反而让 Ctrl+Click 跳转失效、补全卡顿、LSP 端口被抢。
-
wingrunr21.vscode-ruby（蓝宝石图标）：唯一支持 Ruby 3.2+ 语法和 RBS 推导的语言服务；在设置里清空ruby.lint（设为[]），否则和 RuboCop 冲突 -
ruby-rubocop：提供实时检查和自动修复，依赖本地rubocopgem，建议bundle add rubocop --group=development - Rails 用户可加
shawncarter.rails-run-specs：直接点行号跑单个it块，比手敲rspec spec/models/user_spec.rb:24快得多 - 删掉所有带
rebornix.ruby（红宝石图标旧版）、ruby-solargraph、ruby-test、fxa90111.ruby-debug的扩展
最易被忽略的一点：VSCode 状态栏左下角显示 Ruby x.x.x，才是它真正“认出” Ruby 的唯一可信信号；其他任何提示（比如插件已启用、LSP 标签亮了）都不算数——因为那只是前端在跑，后端语言服务器可能根本没连上。
