vscode本身不管理ruby环境，所有功能依赖终端中可用的ruby和bundle；若which ruby在vscode终端输出/usr/bin/ruby，说明未加载shell配置，需检查~/.zprofile或path设置，并确保安装wingrunr21.vscode-ruby、ruby-rubocop、castwide.ruby-lsp三插件，调试必须用debug gem并配launch.json。
VSCode 本身不管理 Ruby 环境，所有插件功能（跳转、补全、调试）都依赖终端里能跑起来的那个 ruby 和 bundle。如果你在外部终端里 ruby -v 是 3.2.2，但在 VSCode 集成终端里是 /usr/bin/ruby 或直接报 command not found，后面所有配置都是白搭。
which ruby 在 VSCode 终端里输出 /usr/bin/ruby？立刻检查 shell 初始化加载
这是 macOS/Linux 用户最常卡住的点：VSCode 启动时不读 ~/.zshrc 或 ~/.bash_profile，而是用一个“干净”的环境快照。即使你在 iTerm 里一切正常，VSCode 也看不到 rbenv/rvm 的 shims。
- 在 VSCode 集成终端里运行
which ruby和echo $PATH，和系统终端对比；路径不一致就说明环境隔离了 - macOS 用户优先把
rbenv init输出的eval行加到~/.zprofile（不是~/.zshrc），然后完全退出 VSCode（Cmd+Q），再重开 - Windows 用户若用 RubyInstaller，必须勾选 “Add Ruby executables to your PATH”；否则手动把
C:\Ruby32-x64\bin加进系统环境变量，再重启 VSCode - 验证成功标志：VSCode 状态栏左下角显示
Ruby 3.x.x，且which ruby输出含.rbenv/shims或.rvm/rubies
只装这三个扩展：wingrunr21.vscode-ruby + ruby-rubocop + castwide.ruby-lsp
VSCode 插件市场搜 “ruby” 出来的二十多个扩展里，90% 已停更、冲突或功能重叠。装多了反而抢端口、让 Ctrl+Click 跳转失效、甚至导致 LSP 启动失败。
-
wingrunr21.vscode-ruby（蓝宝石图标）：目前唯一持续维护、支持 Ruby 3.1+ 语法（如then、def foo(**opts)）的插件；务必在设置里关掉它的内置 linter："ruby.lint": []，否则和 RuboCop 冲突 -
ruby-rubocop：提供实时语法检查和自动修复；它调用的是本地rubocopgem，不是全局安装的，建议bundle add rubocop --group=development -
castwide.ruby-lsp：当前推荐的语言服务器；但注意——它只是前端，真正起作用的是你本地装的ruby-lspgem，不是插件本身 - 必须卸载：
rebornix.ruby（已停更）、ruby-solargraph（Solargraph 2024 年起不再发布）、ruby-test（功能被 rspec 插件替代）
ruby-lsp 必须本地 gem install，且路径要对得上项目 Ruby 版本
castwide.ruby-lsp 插件只是个壳，它启动时会去 PATH 里找 ruby-lsp 可执行文件。如果没装、版本太旧、或 Ruby 版本不匹配，Output 面板 → “Ruby LSP” 会显示 Failed to start language server，但界面毫无提示。
- 在项目根目录运行：
gem install ruby-lsp；如果你用 rbenv，先确认当前版本：rbenv local 3.2.2，再装 - Ruby 2.6 以下不兼容最新
ruby-lsp，会静默失败；建议最低用 3.1+ - 项目有
Gemfile？在插件设置里把rubyLsp.serverPath改成bundle exec ruby-lsp，否则 LSP 无法加载Gemfile.lock锁定的依赖 - 首次打开 Rails 项目时，
ruby-lsp可能卡在 “Indexing…” 十几秒，属正常；别急着关掉重试
调试必须配 launch.json，且用 debug gem 不是 ruby-debug-ide
VSCode Ruby 调试器不支持零配置启动。按 F5 报 No configuration found for launch 或断点变灰，基本是因为 .vscode/launch.json 缺失、字段错位，或用了已废弃的 ruby-debug-ide。
- Ruby 3.1+ 彻底移除了
debugger方法，byebug和ruby-debug-ide启动即崩溃，错误常见为undefined method `write' for nil:NilClass - 正确做法：在
Gemfile的development组加gem 'debug'，然后bundle install - 必须手动创建
.vscode/launch.json，至少包含一个"type": "Ruby"的 configuration；空文件或缺request字段都会失败 - 调试命令实际走的是
bundle exec rdbg --open --command -- ...，不是直接调ruby；所以确保bundle exec在 VSCode 终端里能正常工作
最容易被忽略的是：VSCode 集成终端是否真正继承了你的 shell 环境。很多问题表面看是插件没反应、跳转失效、断点不命中，根源都在 which ruby 这一步没对齐。不要跳过验证，也不要只信状态栏显示——一定要在集成终端里亲手敲一遍命令。
