Ruby版本必须由rbenv或RVM管理，VSCode不托管运行时，只调用终端环境；直接用系统Ruby会导致gem权限失败、bundle行为不一致、调试器启动即退出。
ruby 版本必须由 rbenv 或 rvm 管理，VSCode 本身不托管 Ruby 运行时，只调用终端已加载的环境；直接依赖系统 Ruby（如 macOS 自带的 /usr/bin/ruby）会导致 gem install 权限失败、bundle exec 行为不一致、调试器启动即退出。
为什么 which ruby 在终端和 VSCode 集成终端里结果不同
VSCode 启动时默认不读取你的 shell 初始化文件（如 ~/.zshrc 或 ~/.bash_profile），所以它找不到 rbenv 的 shims 路径，只能 fallback 到系统 Ruby。
- 在终端运行
which ruby和echo $PATH，记下输出 - 在 VSCode 集成终端（
Ctrl + `）中重复执行，对比是否一致 - 如果不一致，在 VSCode 设置中搜
terminal.integrated.env，按 shell 类型添加 PATH 前缀：
例如 zsh 用户加："terminal.integrated.env.zsh": { "PATH": "/Users/you/.rbenv/shims:/usr/local/bin:$PATH" } - Windows 用户若用 msys2 + rbenv，必须确保 VSCode 启动方式是通过 msys2 终端执行
code .，而非双击图标
该装哪些扩展，不该装哪些
插件冲突是 Ruby 支持失效的主因，不是装得越多越好。
- 必装且仅需这 3 个：
castwide.ruby-lsp（语言服务）、misogi.ruby-debug-ide（调试器前端）、ruby-rubocop（代码检查） - 立即卸载：
rebornix.ruby（已停更，与 LSP 抢端口）、ruby-solargraph（Solargraph 已弃用）、shawncarter.rails-run-specs（新版ruby-lsp内置 RSpec 支持） - 在
settings.json中显式关闭旧式路径配置："ruby.interpreterPath"和"ruby.useLanguageServer"都不要设，让ruby-lsp自动探测 - 如果项目用 Bundler，确认
ruby-lsp能读到Gemfile：必须在项目根目录打开工作区，子目录打开会失效
调试断点不命中或启动就报错
根本原因是调试器和 gem 不匹配——ruby-debug-ide + debase 在 Ruby 3.1+ 上已不可用，byebug 更是彻底失效。
- 在
Gemfile中加：gem "debug", group: :development, require: false，然后bundle install - 验证是否生效：
bundle exec ruby -e "require 'debug'; puts 'ok'"，输出ok才算对 -
.vscode/launch.json必须长这样（Rails 示例）：{ "version": "0.2.0", "configurations": [ { "name": "Rails Server", "type": "Ruby", "request": "launch", "program": "${workspaceFolder}/bin/rails", "args": ["server", "-p", "3000"], "cwd": "${workspaceFolder}" } ] } - 别在
config/application.rb或config/boot.rb里打断点——这些文件在debug加载前就执行完了；断点只对app/、lib/下被require或autoload的文件有效
rspec / rails 命令在 VSCode 里报错“Don't know how to build task”
不是命令写错了，是 VSCode 插件没走 bundle exec，而是直接调用了全局安装的 rspec 或 rake 可执行文件。
- 在项目根目录的
.vscode/settings.json中强制所有 Ruby 工具走 Bundler："ruby.lsp.bundlePath": "bundle", "ruby.formatting.prettierPath": "bundle exec rufo", "ruby.test.rspec.execPath": "bundle exec rspec"
- 确保
ruby-rubocop插件也走 bundle："ruby.rubocop.executePath": "bundle exec rubocop" - VSCode 里右键 Run Test 时，它实际执行的是
bundle exec rspec spec/models/user_spec.rb:24，不是rspec；如果仍失败，手动在集成终端跑一遍看报什么错，大概率是GEM_HOME或BUNDLE_GEMFILE没继承过来
rbenv shim、bundle 上下文、ruby-lsp 启动时机、debug gem 加载顺序——漏掉任意一环，就会表现为“语法高亮没了”“跳转进不去”“断点灰了”“测试跑不通”，但错误信息往往不指向真正原因。 
