vscode不管理ruby环境，必须在已激活rbenv/rvm的终端中执行code .启动；集成终端不加载shell配置导致路径缺失；调试须用debug gem、禁用zeitwerk、每次环境变更后重启vscode窗口。
VSCode本身不管理Ruby环境，所有Gem加载、bundle exec行为、调试器启动都依赖终端继承的rbenv/rvm上下文——双击图标打开VSCode，bundle install成功但rails server报Could not find gem，就是这个原因。
为什么code .必须在已激活Ruby环境的终端里执行
VSCode集成终端默认不加载shell配置（如~/.zshrc里的rbenv init -），导致$GEM_HOME、$GEM_PATH、$PATH缺失。直接双击打开时，which ruby会指向/usr/bin/ruby或报错，而终端里运行正常。
- 验证方式：在VSCode集成终端中执行
echo $SHELL和which ruby，输出必须和你在项目根目录手动开终端时一致 - 修复动作：永远用
cd /path/to/your/rails/app && code .启动，别用图形界面图标 - Windows用户注意：msys2 + rbenv 是唯一稳定组合；WSL路径下的ruby会被
ruby-rubocop插件拒绝识别
debug gem 是当前唯一可用的调试依赖（不是byebug或ruby-debug-ide）
Ruby 3.1+ 已彻底移除byebug兼容层，ruby-debug-ide在3.0+上会触发undefined method `write' for nil:NilClass并静默退出。官方debug gem是唯一被VSCode Ruby Debug插件（fxn.vscode-ruby-debug）支持的后端。
- 在
Gemfile中添加：gem "debug", group: :development, require: false - 运行
bundle install，再验证：bundle exec ruby -e "require 'debug'; puts 'ok'" - 删掉所有
binding.pry、byebug调用，它们会阻塞debug的断点注册 - 不要装
rebornix.ruby（红宝石图标）——它已停更，且与debug冲突
config.autoloader = :classic 是Rails 7+调试进app/models的前提
Rails 7默认启用:zeitwerk自动加载，但它对调试器路径监听不敏感。VSCode断点能进app/controllers但跳过app/models，90%是因为zeitwerk缓存未刷新或路径未被debug识别。
- 在
config/environments/development.rb中强制设为：config.autoloader = :classic - 每次改完配置，先在终端运行：
bin/rails tmp:clear，否则旧缓存会让断点跳转到错误文件 - 如果仍不生效，在
launch.json的env字段加"RUBY_DEBUG_NO_RAILS": "1"临时禁用Rails集成——能进模型说明确实是autoload干扰 - 别在
.vscode/settings.json里硬写"ruby.interpreterPath"，这会绕过rbenv shim，导致bundle exec失效
bundle exec不是建议，是VSCode里所有Ruby命令的执行前提
VSCode插件（如ruby-rubocop、rspec运行器）默认调用$PATH里第一个可执行文件，不是Gemfile.lock锁死的版本。结果就是本地rspec跑通，VSCode里点“Run Test”却报undefined method `allow'（Rspec 2语法被Rspec 3执行）。
- 在项目根目录
.vscode/settings.json中显式声明："ruby.lsp.bundlePath": "bundle" - 格式化工具也要走bundle：
"ruby.formatting.prettierPath": "bundle exec rufo" - 运行rake任务时，必须显式传
RAILS_ENV：bundle exec rake db:migrate RAILS_ENV=development，VSCode不自动注入该变量 - 调试Rails服务器的
launch.json里，program必须是${workspaceFolder}/bin/rails，args填["server", "-p", "3000"]，不能写rails server
最易被忽略的点：每次切换Ruby版本（rbenv local）、更新Gemfile、或修改config/environments/development.rb后，必须重启VSCode整个窗口——仅重启集成终端或重载窗口不够，LSP服务和调试器进程不会自动重新绑定新环境。
