Solargraph在VSCode中启动失败通常因Ruby环境未正确配置，需确认ruby≥2.6、solargraph gem已安装、VSCode从终端启动（rbenv/rvm用户）、路径无空格/中文、项目有Gemfile或配置.solargraph.yml，并重启服务或重建索引。
Ruby环境没装好，solargraph 启动直接报错
VSCode 里 Solargraph 插件起不来，大概率不是插件问题，而是 Ruby 运行时或语言服务器根本没跑起来。Solargraph 依赖系统已安装的 Ruby（不是 VSCode 自带的），且要求 gem 可用、bundle 能识别项目结构。
- 先在终端运行
ruby -v和gem list solargraph，确认 Ruby 版本 ≥ 2.6，且solargraphgem 已全局或项目内安装（推荐用gem install solargraph） - 如果用
rbenv或rvm，确保 VSCode 是从终端启动（比如终端里执行code .），否则它看不到 shell 的 Ruby 环境 - Windows 用户注意：WSL 下装的 Ruby 对 Windows 原生 VSCode 不可见，要么改用 WSL 版 VSCode，要么在 Windows 上单独装 Ruby（推荐 RubyInstaller + DevKit）
Solargraph插件提示“Server initialization failed”
这通常是 solargraph 服务启动时卡在某一步，比如找不到 Gemfile、解析 .rb 文件出错，或权限/路径里有空格/中文。
- 检查项目根目录是否有
Gemfile；没有的话，Solargraph 会退回到“无 bundle 模式”，但无法跳转到 gem 内部方法 —— 建议补一个空Gemfile并运行bundle install - VSCode 设置里搜
solargraph.autoStart，设为true；再搜solargraph.commandPath，手动填上完整路径，比如/Users/xxx/.rbenv/shims/solargraph（macOS）或C:\Ruby31-x64\bin\solargraph.bat（Windows） - 如果项目路径含空格或中文，Solargraph 旧版本（≤ 0.44）会解析失败；升级到最新版
solargraphgem（gem update solargraph）可缓解
Ruby代码里跳转不到定义、不提示方法参数
不是插件坏了，是 Solargraph 没完成索引，或者当前文件没被纳入分析范围。它默认只扫描 **/*.rb，且对 require / autoload 路径敏感。
- 打开命令面板（
Cmd+Shift+P/Ctrl+Shift+P），运行Solargraph: Restart Server；等右下角出现 “Indexing completed” 才算就绪 - 检查 VSCode 左下角状态栏是否显示
Ruby（不是Plain Text）；点它手动选为 Ruby 语言模式，否则 Solargraph 不响应 - 若用
zeitwerk或自定义$LOAD_PATH，需在项目根建.solargraph.yml，显式加require_paths，例如：require_paths: - lib - app/models
为什么改了 Ruby 代码，Solargraph 提示还是旧的？
Solargraph 默认缓存索引，不会实时监听所有文件变更，尤其在大型项目中靠轮询效率低，容易滞后。
- 保存文件后没反应？先试
Solargraph: Rebuild Workspace（比 Restart 更彻底，会清缓存重扫） - 频繁修改又不想手动重建？在
.solargraph.yml里加watcher: true，但注意这会增加内存占用，老旧机器可能卡顿 - 某些 DSL（如 Rails 的
belongs_to）或动态方法（define_method）Solargraph 天然不识别 —— 这不是配置问题，是静态分析局限，别硬调
最常被忽略的是：Solargraph 不处理 eval、instance_eval、send 这类运行时行为，提示缺失时先看是不是这类动态调用。它能做的，是把已知路径下的静态结构理清楚。
