Solargraph启动慢、补全卡顿主因是项目索引未精准配置：需在.solargraph.yml中显式设置require_paths（如app/domain/lib），Rails 7+须用bundle exec solargraph bundle构建索引，并排除node_modules等干扰目录。
为什么Solargraph启动慢、补全卡顿
Solargraph不是“装上就快”的语言服务器，它启动时要扫描整个项目结构并构建类型索引，尤其在 Rails 项目里，没配对就会反复重扫或漏扫。常见现象是敲 user. 后等 2–3 秒才弹出方法列表，甚至直接不响应。
- 默认只扫描
**/*.rb，如果你的代码在app/domain或lib/core下，必须在.solargraph.yml里显式加require_paths - Rails 7+ 的
zeitwerkautoloader 会让 Solargraph 无法推断动态加载路径，补全belongs_to或form_with会失效——得运行bundle exec solargraph bundle（不是裸跑solargraph bundle） - VSCode 终端里
which solargraph返回空？说明 PATH 没继承，得在设置里补terminal.integrated.env.zsh，把~/.rbenv/shims加进去 - 别开
solargraph.autoInstall：自动安装常拉低版本，新版solargraph（≥ 0.45）对空格/中文路径容忍度高，且增量更新更稳
Debug 启动失败或断点不触发的硬伤点
VSCode 的 Ruby Debug 插件本身不崩溃，但和底层 gem 链路一断，F5 就静默失败——你看到的是“调试已停止”，实际是 ruby-debug-ide 进程根本没起来。
- Ruby 3.1+ 必须用
debuggem，不是ruby-debug-ide：后者在新版本里频繁 segfault，gem install debug+bundle add debug --group development才可靠 -
launch.json里type字段必须是"ruby"，不是"Ruby"或"RUBY"；program推荐设为"${workspaceFolder}/bin/rails"，args填["server"]，别写rails server - Rails 7 默认开启 bootsnap，它会缓存 require 路径，导致断点跳到旧文件——临时加环境变量
"DISABLE_BOOTSNAP": "1"到launch.json的env字段 - 别混插件：卸掉
rebornix.Ruby和fxa90111.ruby-debug，只留fxn.vscode-ruby-debug—— 它专为debuggem 设计，协议层对齐
VSCode 自身拖慢 Ruby 工具链的隐藏开关
VSCode 默认配置对 Ruby 项目很“奢侈”：它监听所有子目录、渲染每行空格、预加载符号表……这些在 Rails 大项目里直接吃光内存，连带 Solargraph 和 Debug 进程被系统 kill。
-
files.watcherExclude必设：至少加"**/node_modules/**"、"**/tmp/**"、"**/log/**"，否则文件变更事件泛滥，Solargraph 会反复重建索引 -
editor.renderWhitespace设为"none"：空格可视化在 Ruby 里几乎无用，却占 GPU 内存，尤其开多个 .erb 文件时明显卡顿 - 关掉
search.quickOpen.includeSymbols：Solargraph 的符号索引和 VSCode 自己的符号扫描打架，关掉后 Ctrl+P 查文件更快，且不影响 Solargraph 的 Go to Definition -
files.useExperimentalFileWatcher设为false：macOS 上实验版监听器容易句柄泄漏，回归fs.watch更稳，Solargraph 启动成功率提升明显
重启不是万能解，但必须做对顺序
改完配置不等于生效——Ruby 工具链各环节有依赖顺序，错一步，前面全白调。
- 改完
.solargraph.yml或launch.json后，先在终端手动跑一次bundle exec solargraph bundle和solargraph stdio看是否报错，再进 VSCode - VSCode 必须从终端执行
code .启动，双击图标或 Spotlight 启动会导致 rbenv/shims 不加载，which ruby在集成终端里就变成/usr/bin/ruby - 重启顺序：先 Cmd+Q 彻底退出 VSCode → 终端里确认
ruby -v和solargraph -v输出正常 → 再code .→ 右键任意 .rb 文件 →Solargraph: Restart Server - 别信 “自动重启”：Solargraph 插件的 autoStart 有时只启 socket，但你设了 stdio，得手动切一次传输方式，Cmd+Shift+P →
Solargraph: Select Transport→ 选stdio
