VSCode本身不运行Ruby，点▶️无反应或报command not found: ruby，说明环境未对齐——需先确保which ruby在集成终端输出正确路径（含.rbenv/shims等），再重启VSCode；ruby-lsp插件依赖本地gem install ruby-lsp；调试必须手写launch.json并装debug gem。
VSCode 本身不运行 Ruby，点右上角 ▶️ 没反应、报 command not found: ruby，说明它根本没“看见”你的 Ruby 环境——不是插件装少了，是终端路径没对齐。
which ruby 在 VSCode 终端里没输出？先修环境，别碰插件
VSCode 集成终端启动时，默认不加载你的 ~/.zshrc 或 ~/.bash_profile，导致 rbenv / rvm 的 shims 不生效。结果就是：外部终端一切正常，VSCode 里 which ruby 返回空或指向 /usr/bin/ruby（系统只读 Ruby，gem install 必败）。
- macOS 用户：把
eval "$(rbenv init - zsh)"放进~/.zprofile（不是~/.zshrc），改完后必须 完全退出 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 - 状态栏左下角显示
Ruby 3.x.x才是真正生效的唯一标志
tasks.json 怎么写才能跑通 bundle exec？
VSCode 运行 Ruby 脚本靠的是 tasks.json 调用 shell 命令。直接写 "command": "ruby ${file}" 是错的——JSON 不支持命令拼接，空格会被截断；项目用了 Bundler 却不加 bundle exec，就可能因 gem 版本冲突而报 LoadError。
- 正确写法：把命令和参数分开，
"command": "bundle"，"args": ["exec", "ruby", "${file}"] - 如果只是单文件脚本且没 Gemfile，用
"command": "ruby"+"args": ["${file}"]即可 -
"presentation": {"clear": true}很重要，否则多次运行输出会堆叠，干扰判断 - 保存后按
Ctrl+Shift+B（macOS 是Cmd+Shift+B）触发，输出在集成终端里
ruby-lsp 插件装了但跳转/补全失效？本地 gem 没装或版本不匹配
castwide.ruby-lsp 插件只是前端壳，真正干活的是你本地装的 ruby-lsp gem。只装插件不装 gem，等于买了路由器没接网线——LSP 启动失败，VSCode 就只剩语法高亮。
- 在项目根目录运行
gem install ruby-lsp；如果用rbenv，先rbenv local 3.2.2切到项目对应版本再装 - 项目有
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已停更），二者不能共存
F5 调试报 No configuration found？launch.json 必须手写，debug gem 必须装
VSCode Ruby 调试器不支持零配置启动。没有 .vscode/launch.json，F5 就是摆设；Ruby 3.1+ 彻底移除了 debugger 方法，byebug 和 ruby-debug-ide 全部失效，常见错误是 undefined method `write' for nil:NilClass 或断点灰掉。
- 在项目根目录创建
.vscode/launch.json，内容至少包含"type": "ruby"、"request": "launch"、"program": "${file}" -
Gemfile中加gem "debug", group: :development, require: false，然后bundle install - 验证是否生效：
bundle exec ruby -e "require 'debug'; puts 'ok'"，输出ok才算对 - Rails 项目需额外注意：
config.autoloader = :classic+bin/rails tmp:clear，否则断点常卡在 controller 不进 model
最易被忽略的点：VSCode 必须通过终端执行 code . 启动，双击图标打开会丢失全部 Ruby 环境上下文；ruby-lsp 和 debug gem 必须装在当前 rbenv / rvm 激活的 Ruby 版本下，跨版本安装等于白装。
