Ruby开发环境需配置rbenv管理Ruby版本、安装Solargraph服务、搭配castwide.solargraph插件，并确保索引完成；常见问题可通过切换stdio传输、指定端口或禁用SIP解决。
如果您在使用 VSCode 进行 Ruby 开发时发现代码补全不准确、跳转失效或文档提示缺失，则很可能是 Ruby 语言服务器未正确配置或 Solargraph 服务未正常运行。以下是构建稳定 Ruby 开发环境的具体操作路径：
本文运行环境：MacBook Pro，macOS Sequoia。
一、安装 Ruby 环境与包管理器
VSCode 本身不提供 Ruby 解释器，需先确保系统级 Ruby 可执行环境可用，且支持 gem 包管理。推荐使用 rbenv 或 rvm 统一管理 Ruby 版本，避免与系统 Ruby 冲突。
1、打开终端，执行 brew install rbenv 安装版本管理工具。
2、运行 rbenv install 3.3.0 下载并安装指定 Ruby 版本。
3、执行 rbenv global 3.3.0 设为全局默认版本。
4、运行 rbenv rehash 刷新 shims，使新安装的 Ruby 命令立即生效。
二、安装并启动 Solargraph 服务
Solargraph 是一个基于 Language Server Protocol 的 Ruby 语言服务器，负责提供语义分析、自动补全、跳转定义等核心功能。它必须作为后台服务运行，且需与当前项目 Ruby 版本一致。
1、在终端中进入您的 Ruby 项目根目录。
2、执行 gem install solargraph 安装 Solargraph gem。
3、运行 solargraph bundle 生成项目专属的 .solargraph.yml 配置文件，并扫描依赖。
4、启动服务：执行 solargraph socket 启动基于 TCP 的语言服务器（VSCode Ruby 插件默认连接此端口）。
三、配置 VSCode Ruby 扩展
官方 Ruby 扩展（rebornix.ruby）已停止维护，当前推荐使用 misogi.ruby-rubocop 配合 castwide.solargraph 插件组合。后者专为 Solargraph 设计，可直接对接语言服务器。
1、在 VSCode 扩展市场中搜索并安装 Solargraph 插件（发布者：Castwide）。
2、打开 VSCode 设置（Cmd+,），搜索 solargraph.autoStart，勾选启用自动启动。
3、搜索 solargraph.transport，将其值设为 socket。
4、搜索 solargraph.executablePath，设置为 solargraph（确保该命令在系统 PATH 中可用）。
四、验证项目索引状态
Solargraph 需对项目源码进行静态分析并建立符号索引。若未完成索引，所有智能提示功能将不可用。索引过程依赖于项目中是否存在有效的 Gemfile 和正确的 require 路径声明。
1、确认项目根目录下存在 Gemfile 文件，并已执行过 bundle install。
2、在 VSCode 中打开任意 .rb 文件，右键选择 Solargraph: Restart Server。
3、观察 VSCode 状态栏右下角是否显示 Solargraph ready；若显示 Indexing...，请等待进度完成。
五、处理常见连接失败场景
当 VSCode 提示“Failed to connect to Solargraph”时，可能由端口占用、权限限制或路径解析错误导致。以下三种独立方案可分别尝试：
1、切换为 stdio 传输模式：在设置中将 solargraph.transport 改为 stdio，避免 socket 端口冲突。
2、手动指定 socket 端口：运行 solargraph socket --port 7658，再在 VSCode 设置中填入对应端口号。
3、禁用 macOS SIP 对 /usr/bin/ruby 的拦截：若使用系统 Ruby，改用 rbenv 管理的 Ruby 路径，执行 which ruby 获取路径后，填入 solargraph.executablePath 设置项。
