VSCode不管理Ruby版本，必须用rbenv或RVM配置且确保集成终端加载shell初始化脚本；只保留wingrunr21.vscode-ruby、ruby-rubocop、castwide.solargraph三个扩展；调试必须用debug gem而非ruby-debug-ide；所有命令需通过bundle exec执行以保证版本一致。
VSCode 本身不管理 Ruby 版本，也不自带 Ruby 运行时——你装的任何扩展都只是调用终端里能跑起来的那个 ruby。如果 which ruby 输出的是 /usr/bin/ruby 或路径里不含 .rbenv/.rvm，那后续所有语法高亮、跳转、调试都会出问题，不是报错就是“看起来正常但实际不工作”。
确认 Ruby 环境在 VSCode 终端里真正生效
VSCode 集成终端默认不加载你的 shell 初始化脚本（比如 ~/.zshrc），所以即使你在 iTerm 里 ruby -v 是 3.2.2，VSCode 里可能还是系统 Ruby 2.6。这不是插件问题，是环境没接上。
- 在 VSCode 集成终端里运行
which ruby和ruby -v，输出必须和你在外部终端一致，且路径要含~/.rbenv/shims或~/.rvm/rubies - 如果不对，去 VSCode 设置搜
terminal.integrated.profiles.zsh（或bash），把args改成["-i", "-l"]，强制加载 login shell - macOS 用户特别注意：
zsh的配置文件可能是~/.zprofile而非~/.zshrc，rbenv init输出的那段eval建议加到~/.zprofile里
只留三个关键扩展：wingrunr21.vscode-ruby + ruby-rubocop + castwide.solargraph
VSCode 插件市场搜 “ruby” 出来的二十多个扩展里，绝大多数已停更、冲突或功能重叠。装多了不仅没用，还会抢端口、覆盖设置、让 Ctrl+Click 跳转失效。
-
wingrunr21.vscode-ruby（蓝宝石图标）：目前唯一支持 Ruby 3.1+ 新语法（then、参数解构）、RBS 类型推导的语言服务；关掉它的内置 linter（设ruby.lint为空数组），否则会和 RuboCop 冲突 -
ruby-rubocop：提供实时语法检查和自动修复，依赖本地rubocopgem，别用全局安装，建议bundle add rubocop --group=development -
castwide.solargraph：负责跳转定义、hover 提示、自动补全；必须配"solargraph.useBundler": true，并在项目根目录运行solargraph bundle - 删掉所有带
ruby-solargraph（旧版）、ruby-test、rails、ruby-lsp（已合并进 wingrunr21）的扩展
调试必须用 debug gem，不是 ruby-debug-ide
Ruby 3.1+ 彻底移除了 debugger 方法，而 ruby-debug-ide 依赖它。你按 F5 启动后立刻退出、断点变灰、控制台报 undefined method `write' for nil:NilClass，基本都是这个原因。
- 在
Gemfile的development组里加gem 'debug'，然后bundle install - 验证是否生效：
bundle exec ruby -e "require 'debug'; binding.break"—— 能进交互式调试器就对了 -
launch.json里保持"type": "ruby"，但不要手动指定ruby-debug-ide；VSCode 会自动识别debuggem 并启用它 - 断点只在
require之后的代码里命中，比如app/models/user.rb可以，config/boot.rb不行——这是 Ruby 加载机制决定的，不是配置错误
bundle exec 不是可选项，是所有命令的默认前缀
VSCode 插件调用 rubocop、rspec、rails 时，默认走 $PATH 里第一个可执行文件，而不是你 Gemfile.lock 锁死的版本。结果就是：终端里 rspec 跑通，VSCode 里点 “Run Test” 却报 undefined method `allow'（RSpec 2 语法被 RSpec 3 执行了）。
- 在项目根目录建
.vscode/settings.json，写入：{"ruby.lsp.bundlePath": "bundle"} - 确保
ruby-rubocop扩展的设置里启用了ruby.rubocop.executePath，值设为bundle exec rubocop - 别信“自动检测”，手动指定路径最稳；
which rubocop输出的全局路径大概率不是你要的
最常被忽略的其实是 rbenv rehash 和 VSCode 缓存。改完 .ruby-version 或装完新 gem 后，不运行 rbenv rehash，VSCode 就找不到新命令；不重启窗口（Cmd+Shift+P → Developer: Reload Window），旧的 LSP 连接也不会更新。这些动作看着琐碎，但跳过一次，后面两小时都在查“为什么跳转不工作”。
