需先安装 Ruby 并配置 PATH，再装 wingrunr21.vscode-ruby 插件和 ruby-lsp 语言服务器，调试需 fxruby.vscode-ruby-debug 插件及正确 launch.json，RSpec 测试须通过 bundle exec 运行。
确认 Ruby 是否已安装并被 VS Code 识别
VS Code 本身不自带 Ruby 运行时，必须先在系统中安装 Ruby，否则后续所有插件和调试功能都无法工作。打开终端执行 ruby -v 和 which ruby（macOS/Linux）或 where ruby（Windows），确认输出有效版本号和路径。
常见错误现象：command not found: ruby 或 VS Code 底部状态栏不显示 Ruby 版本。此时不是插件没装对，而是 Ruby 根本没装，或未加入 PATH。尤其 Windows 用户常把 Ruby 安装在非默认路径（如 C:\Ruby32-x64\bin），需手动添加到系统环境变量。
- macOS 推荐用
rbenv或chruby管理多版本，避免与系统 Ruby 冲突 - Windows 用户优先选 RubyInstaller，勾选 “Add Ruby executables to your PATH”
- 验证成功后，重启 VS Code，状态栏左下角应显示类似
Ruby 3.2.2
安装 Ruby 插件并配置语言服务器
VS Code 的 Ruby 支持依赖两个核心组件：语法高亮/跳转的插件 + 提供语义分析的 LSP 服务。官方推荐组合是 rebornix.Ruby（已停更）→ 实际应使用 wingrunr21.vscode-ruby（维护中）+ ruby-lsp 作为语言服务器。
ruby-lsp 是目前最稳定的 Ruby LSP 实现，但需手动安装并确保与项目 Bundler 版本兼容。它不通过 VS Code 插件市场安装，而是在终端中运行：
gem install ruby-lsp
安装后，在 VS Code 设置中搜索 ruby.lspPath，填入 ruby-lsp 可执行文件的绝对路径（例如 /Users/you/.gem/ruby/3.2.0/bin/ruby-lsp）。若留空，插件会尝试自动查找，但容易失败。
- 不要启用
ruby.useLanguageServer以外的旧式 SDK 配置（如ruby.interpreterPath），它们已过时且与 LSP 冲突 - 若项目使用
bundle exec启动（如 Rails），确保ruby-lsp能读取Gemfile—— 它会自动加载 bundle 环境 - 首次打开大型 Rails 项目时，
ruby-lsp可能卡在 “Indexing…” 几十秒，属正常现象
调试 Rails/Web 应用时的关键配置
VS Code 默认不支持 Ruby 调试，需额外安装 fxruby.vscode-ruby-debug 插件，并确保系统已安装 debug gem（Rails 7+ 默认包含，老版本需手动加到 Gemfile）。
调试启动依赖 .vscode/launch.json。对 Rails Web 应用，最简可用配置如下：
{
"version": "0.2.0",
"configurations": [
{
"name": "Rails Server",
"type": "Ruby",
"request": "launch",
"cwd": "${workspaceFolder}",
"program": "${workspaceFolder}/bin/rails",
"args": ["server", "-p", "3000"],
"env": {
"RAILS_ENV": "development"
}
}
]
}
注意点：
-
program必须指向bin/rails（而非rails全局命令），才能正确加载项目 bundle - 若使用
spring，调试前先运行bin/spring stop，否则断点可能不触发 - 在控制器或视图里打断点后，需用浏览器访问对应 URL（如
http://localhost:3000/posts），调试器才会激活 - 不建议用
pry-byebug+ 终端rails server混合调试 —— VS Code 的调试器与之互斥
运行 RSpec 测试时的常见陷阱
VS Code 可直接运行单个测试文件或测试方法，但前提是项目已正确配置 rspec 且 bundle exec rspec 在终端中能跑通。插件 howardzhang77.vscode-ruby-rspec 提供右键菜单“Run RSpec”，但它底层仍调用 shell 命令。
典型失败场景：Could not find 'rspec' (>= 0.a) among X total gem(s)。这说明插件没走 bundle 环境，而是用了全局 Ruby 的 gempath。
- 解决方案：在
.vscode/settings.json中强制指定 bundle 执行路径："ruby.testFramework.rspec.path": "bundle exec rspec" - 确保
rspecgem 在Gemfile的:test或:developmentgroup 中，并已运行bundle install - 若测试报错涉及数据库（如
ActiveRecord::NoDatabaseError），检查RAILS_ENV是否为test，且db:test:prepare已执行
Ruby 的环境链比 Node.js 或 Python 更隐晦：系统 Ruby → rbenv/rvm → bundle → spring → rails server → rspec。任一环缺失或路径错位，VS Code 就会表现成“功能失效”，实际问题往往不在编辑器本身。
