VSCode运行Ruby脚本需确保终端能识别ruby命令，Mac用户检查~/.zshrc并重启VSCode，Windows用户确认CMD/PowerShell中ruby可用；Ruby LSP插件需配合本地ruby-lsp gem使用；调试必须配置.launch.json，且ruby-debug-ide与Ruby版本要匹配。
Ruby脚本在VSCode里直接点“运行”没反应？先确认终端是否识别ruby
VSCode本身不执行Ruby，它靠系统终端调用ruby命令。如果点右上角▶️没反应、或报command not found: ruby，大概率是环境变量没进VSCode的启动上下文。
- Mac用户：检查
~/.zshrc（或~/.bash_profile）里是否正确导出了ruby路径，比如export PATH="/opt/homebrew/bin:$PATH"；然后**完全退出VSCode再重开**——它不会自动继承新shell的环境 - Windows用户：确认
ruby在CMD和PowerShell里都能执行；若用Git Bash装的Ruby，VSCode默认不读它的.bashrc，得在VSCode设置里改终端类型，或改用Windows Terminal作为默认 - 验证方式：在VSCode集成终端里输入
which ruby（Mac/Linux）或where ruby（Windows），必须有输出
装了Ruby LSP插件但跳转/补全无效？检查ruby-lsp gem是否已安装且版本匹配
Ruby LSP插件（如“Ruby Solargraph”已停更，主流是“Ruby LSP”官方插件）依赖本地ruby-lsp gem提供语言服务。只装插件不装gem，等于买了路由器没接网线。
- 必须在项目根目录下运行
gem install ruby-lsp；如果用rbenv或rvm，确保当前shell的Ruby版本与项目一致，再装 - 某些旧版Ruby（如2.6以下）不支持最新
ruby-lsp，会静默失败；查插件输出面板（View → Output → Ruby LSP），看到Failed to start language server就说明gem启动失败 - 如果项目用Bundler，建议用
bundle exec ruby-lsp启动服务——这时要在插件设置里把rubyLsp.serverPath改成bundle exec ruby-lsp
按F5调试报错No configuration found for launch？手动配launch.json是唯一解
VSCode Ruby调试器（ruby-debug-ide + debase）不支持零配置启动，必须有.vscode/launch.json。别信“装完插件就能F5”的说法。
- 最简可用配置：
{ "version": "0.2.0", "configurations": [ { "name": "Debug Current Script", "type": "Ruby", "request": "launch", "cwd": "${workspaceFolder}", "program": "${file}", "env": {} } ] } - 注意
"type": "Ruby"对应的是rebornix.ruby插件（老但稳定），不是ruby-lsp插件——后者只做LSP，不负责调试 - 如果项目用RVM/rbenv，调试时可能找不到Gem，需在
env里显式加RUBYOPT: "-I./lib"或GEM_HOME路径
为什么puts输出卡住、断点不触发、或调试器连不上？多半是ruby-debug-ide版本冲突
新版Ruby（3.1+）默认禁用eval类调试机制，而老版ruby-debug-ide依赖它。结果就是调试器进程起来但无法注入、断点灰掉、控制台无输出。
- Ruby 3.1+ 必须用
ruby-debug-ide≥ 2.7.0 +debase≥ 2.4.0；运行gem list | grep debug确认版本 - 如果用了
bundle exec跑脚本，调试时也得用bundle exec rdebug-ide，否则加载的是全局gem，版本对不上 - VSCode里启动调试后，看底部状态栏有没有显示
Ruby Debug；没有就说明调试器根本没连上，优先查launch.json里的program路径是否指向真实.rb文件（不能是symlink，也不能含空格）
Ruby生态工具链的“隐性耦合”特别多：LSP插件和ruby-lsp gem要匹配，调试器和Ruby版本要匹配，终端环境和VSCode启动方式也要匹配。漏掉其中一环，表面看只是“运行不了”，实际是整个链路断在某个看不见的环节。
