Ruby开发环境必须统一版本管理（rbenv/RVM）、插件配置（Ruby LSP+Ruby Debug）、执行路径（bundle exec）和调试依赖（debug gem在development组），否则导致gem加载失败、断点失效、测试崩溃等问题。
Ruby版本管理必须用rbenv或RVM，别直接装系统Ruby
macOS自带的ruby是只读系统路径、无法安装gem、升级会破坏系统工具（比如brew依赖的json gem），Linux发行版预装的也常缺devkit头文件。直接sudo apt install ruby或brew install ruby看似快，但后续bundle install大概率报cannot load such file -- openssl或Failed to build gem native extension。
实操建议：
- macOS / Linux 推荐用
rbenv：执行curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash，再把~/.rbenv/bin加进$PATH，最后rbenv install 3.2.2+rbenv global 3.2.2 - Windows 必须用
msys2+ruby-installer-devkit，别用WSL里装的Ruby——VSCode的ruby-rubocop插件不识别WSL路径里的ruby可执行文件 - 装完立刻验证：
which ruby输出应含.rbenv或.rvm，且ruby -v和gem env home指向用户目录，不是/usr或/opt
VSCode插件要选对，别装“Ruby”官方那个老掉牙的
微软官方的Ruby插件（id: rebornix.ruby）已两年没更新，不支持ruby-lsp，调试器ruby-debug-ide在Ruby 3+里直接崩溃。它还会和solargraph抢language server端口，导致跳转失效。
实操建议：
- 必装
Ruby LSP（id: castwide.ruby-lsp）：自动检测Gemfile，启用solargraph或ruby-lsp服务，支持Ctrl+Click跳转、hover看类型、rename重命名 - 调试用
Ruby Debug（id: misogi.ruby-debug-ide）：注意它依赖debuggem（不是ruby-debug-ide），项目根目录运行bundle add debug，再配launch.json里"type": "ruby"和"request": "launch" - 禁用所有带
ruby-solargraph、ruby-rubocop（旧版）、ruby-test的插件——它们和Ruby LSP冲突，且rubocop现在该走ruby-lsp内置集成
bundle exec不是可选项，是VSCode里Ruby命令的默认前缀
VSCode插件调用rubocop、rspec、rails时，默认走$PATH里第一个可执行文件，不是你Gemfile.lock锁死的版本。结果就是：本地rspec跑通，VSCode里点“Run Test”却报undefined method `allow' for #<:examplegroups::user></:examplegroups::user>（Rspec 2语法被Rspec 3执行了）。
实操建议：
- 在项目根目录建
.vscode/settings.json，写入：{"ruby.lsp.bundlePath": "bundle", "ruby.formatting.prettierPath": "bundle exec rufo"} - 所有终端任务（如
Tasks: Run Task）的command字段必须写bundle exec rspec，不能只写rspec - 如果用
rails生成器，VSCode的Terminal里先cd进项目根，再bundle exec rails g controller Users——否则生成的文件可能引用错误版本的actionpack
调试时binding.break不生效？检查debug gem是否在development组
在代码里写binding.break后VSCode没停住，常见原因是debug gem被放在test组或没加require: false，导致rails server启动时根本没加载它。另一个坑是config/environments/development.rb里config.consider_all_requests_local = false关了调试页面，但不影响断点，只是容易误判。
实操建议：
- 确认
Gemfile里是gem "debug", group: :development，不是group: :test，也不是require: false（debug需要自动require） - 重启
Ruby LSP服务：Cmd/Ctrl+Shift+P → “Ruby LSP: Restart Server”，它会重新加载bundle环境 - 断点只对
rails server、rails console、rspec生效，对ruby script.rb这种单文件脚本需手动加require "debug"，否则binding.break被忽略
Ruby开发环境最麻烦的从来不是装什么，而是每个环节都得对齐：rbenv版本、Gemfile锁定、VSCode插件配置、终端执行路径——漏一个，bundle exec就变成摆设，binding.break就成哑巴。
