故障排除

Ruby LSP 如何激活

Ruby LSP 扩展像任何其他 VS Code 扩展一样，在 VS Code 的 NodeJS 运行时中运行。这意味着在您的 shell 中正确设置的环境变量可能不存在于 NodeJS 进程中。为了使用与项目相同的 Ruby 版本运行 LSP 服务器，我们需要正确设置这些环境变量，这通过调用您的 Ruby 版本管理器来完成。

该扩展使用 shell 的交互模式运行命令，以便自动拾取在 ~/.zshrc 等文件中配置的版本管理器。然后，该命令将环境信息导出为 JSON，以便我们可以将其注入到 NodeJS 进程中，并适当地设置 Ruby 版本和 gem 安装路径。

例如，使用 rbenv 作为版本管理器的 zsh 的激活脚本如下所示

# Invoke zsh using interactive mode (loads ~/.zshrc) to run a single command
# The command is `rbenv exec ruby`, which automatically sets all relevant environment variables and selects the
# specified Ruby version
# We then print the activated environment as JSON. We read that JSON from the NodeJS process to insert the needed
# environment variables in order to run Ruby correctly
/bin/zsh -ic 'rbenv exec ruby -rjson -e "puts JSON.dump(ENV.to_h)"'

激活 Ruby 版本后，我们继续启动服务器 gem (ruby-lsp)。为了避免用户在其 Gemfile 中包含 ruby-lsp，我们在项目内的 .ruby-lsp 目录下创建一个 组合包。

常见问题

用户在激活期间通常会遇到几个主要的问题来源：版本过时、shell 问题或 Bundler 相关问题。

版本过时

如果使用 VS Code，则扩展的版本与服务器（ruby-lsp gem）的版本不同。您可以在状态中心检查服务器版本。

在大多数情况下，服务器 gem 将会自动更新。您还可以使用 VS Code 中的“更新语言服务器 gem”命令触发手动更新。

您还可以尝试从命令行使用 BUNDLE_GEMFILE=.ruby-lsp/Gemfile bundle update ruby-lsp 进行更新

如果您使用任何附加 gem，例如 ruby-lsp-rspec，那么 ruby-lsp 也将存在于您的 Gemfile.lock 中，并且过时的附加组件可能会阻止 ruby-lsp 更新。

无法更新 ruby-lsp gem 的另一种可能情况是，它的运行时依赖项之一受到应用程序中另一个 gem 的限制。例如，Ruby LSP 依赖于 RBS v3。如果另一个 gem 将 RBS 的版本限制为较旧的版本，则无法使用较新版本的 Ruby LSP。

Ruby LSP 的 3 个运行时依赖项是 rbs、prism 和 sorbet-runtime。如果其中任何一个受到应用程序的限制，则 Ruby LSP 可能无法更新。

运行 BUNDLE_GEMFILE=.ruby-lsp/Gemfile bundle outdated 可能有助于了解哪些内容受到限制。

Shell 问题

当扩展程序调用 shell 并加载其配置文件（~/.zshrc、~/.bashrc 等）时，它容易受到 shell 或其插件与 NodeJS 进程交互方式可能导致的问题的影响。例如

  • 某些插件完全重定向 stderr 管道以实现其功能（在 Ruby LSP 端通过 https://github.com/Shopify/vscode-ruby-lsp/pull/918 修复）
  • 如果某些插件检测到 shell 进程没有附加 UI，则会立即失败或陷入无限循环。在这种情况下，无法从 Ruby LSP 端修复，因为 NodeJS 调用的 shell 永远不会有 UI

此外，一些用户遇到 VS Code 选择错误的 shell，不遵守 SHELL 环境变量的问题。这通常会导致选择 /bin/sh 而不是您的实际 shell。如果您遇到此问题，请尝试

  • 将 VS Code 更新到最新版本
  • 完全关闭 VS Code 并从终端使用 code . 启动它（而不是从启动图标打开 VS Code）

有关此问题的更多信息，请访问 https://github.com/Shopify/vscode-ruby-lsp/issues/901。

Bundler 问题

首先，请确保您使用的是最新版本的 Bundler（运行 bundle update --bundler）。

如果扩展程序成功激活了 Ruby 环境，则在尝试组合用于运行服务器 gem 的组合包时，仍可能失败。这可能是常规的 Bundler 问题，例如由于版本要求冲突而无法满足依赖项，或者可能是配置问题。

例如，如果项目将其 linter/formatter 放入可选的 Gemfile 组，并且该组在 Bundler 配置中被排除，则 Ruby LSP 将无法看到这些 gem。

# Gemfile

# ...

# If Bundler is configured to exclude this group, the Ruby LSP will not be able to find `rubocop`
group :optional_group do
  gem "rubocop"
end

如果您遇到与 Bundler 相关的问题，请仔细检查您的全局和项目特定配置，以查看是否有任何可能阻止服务器启动的问题。您可以使用以下命令打印您的 Bundler 配置

bundle config

保存时格式化对话框不会消失

当 VS Code 请求格式化文档时，它会在发送请求后几秒钟打开一个显示进度的对话框，并在服务器响应格式化结果后关闭该对话框。

如果您看到对话框没有消失，这很可能并不意味着格式化花费很长时间或挂起。这很可能意味着服务器崩溃或进入损坏状态，并且只是不响应任何请求，这意味着对话框永远不会消失。

这始终是服务器中的错误导致的结果。它应该始终正常失败，而不会进入阻止其响应来自编辑器的新请求的损坏状态。如果您遇到这种情况，请在此处提交错误报告，其中包含导致服务器卡住的步骤。

缺少的功能

如果您发现某些功能（例如格式化）正常工作，而其他功能（例如转到定义）无法正常工作，并且正在使用 Sorbet 的代码库，则可能表明 Sorbet LSP 没有运行。为了避免重复/冲突的行为，当检测到 Sorbet 代码库时，Ruby LSP 会禁用某些功能，目的是让 Sorbet 提供更好的准确性。

Gem 安装位置和权限

要启动 Ruby LSP 服务器，必须安装 ruby-lsp gem。为了自动索引项目的依赖项，还必须安装它们，以便我们可以读取、解析和分析它们的源文件。ruby-lsp gem 通过 gem install（使用 RubyGems）安装。项目依赖项通过 bundle install（使用 Bundler）安装。

如果您使用非默认路径来安装 gem，请记住，RubyGems 和 Bundler 需要单独的配置才能实现此目的。

例如，如果您配置 BUNDLE_PATH 指向 vendor/bundle，以便 gem 安装在与项目相同的目录中，则 bundle install 将自动拾取它并将它们安装在正确的位置。但是 gem install 不会，因为它需要不同的设置才能实现此目的。

您可以使用 ~/.gemrc 文件来应用您首选的 RubyGems 安装位置。在该文件中，您可以决定使用 --user-install 进行安装，或者使用 --install-dir 选择特定的安装目录。

gem: --user-install
# Or
gem: --install-dir /my/preferred/path/for/gem/install

如果用户没有默认 gem 安装目录的权限，并且 gem install 失败，则此方案非常有用。例如，在某些 Linux 发行版上使用系统 Ruby 时。

使用非默认的 gem 安装路径可能会导致与版本管理器的其他集成问题。例如，对于 Ruby 3.3.1，默认的 GEM_HOME 是 ~/.gem/ruby/3.3.0（不包含版本的补丁部分）。但是，chruby

（以及其他可能的版本管理器）会覆盖 GEM_HOME 以包含版本补丁，从而导致 ~/.gem/ruby/3.3.1。当您使用 gem install --user-install 安装 gem 时，RubyGems 会忽略 GEM_HOME 覆盖并将 gem 安装在 ~/.gem/ruby/3.3.0 中。这导致找不到可执行文件，因为 chruby 修改了 PATH，使其仅包含在 ~/.gem/ruby/3.3.1 下安装的可执行文件。

类似地，大多数版本管理器不会读取您的 ~/.gemrc 配置。如果您使用 --install-dir 进行自定义安装，则版本管理器不太可能知道它。这可能会导致找不到 gem 可执行文件。

RubyGems 和版本管理器（如上所述）之间的不兼容性超出了 Ruby LSP 的范围，应向 RubyGems 或相应的版本管理器报告。

在容器上开发

请参阅文档。

诊断问题

许多激活问题都与您的开发环境配置方式有关。如果您可以重现您遇到的问题，包括有关这些步骤的信息是确保我们能够及时解决问题的最佳方式。请在您的错误报告中包含诊断时所采取的步骤。

检查服务器是否正在运行

检查状态中心。服务器状态是否显示正在运行？如果它正在运行，但您缺少某些功能，请查看我们的功能文档，以确保我们已经添加了对其的支持。

如果该功能被列为完全支持，但对您不起作用，请报告一个问题，以便我们提供帮助。

检查 VS Code 输出选项卡

许多激活步骤都记录在 VS Code 的 Output 选项卡的 Ruby LSP 通道中。检查日志以查看是否有任何条目提示可能存在的问题。扩展是否选择了您首选的 shell？

它是否选择了您首选的版本管理器？您可以使用 "rubyLsp.rubyVersionManager" 设置定义要使用的版本管理器。

启用日志记录

您可以启用日志记录到 VS Code 输出选项卡，如 CONTRIBUTING 文档中所述。

环境激活失败

我们在此文档中列出了版本管理器相关的信息和提示。

我首选的版本管理器不受支持

我们默认支持最常见的版本管理器，但这可能无法覆盖所有可用的工具。对于这些情况，我们提供自定义激活支持。更多信息请参见版本管理器文档。

尝试手动运行 Ruby 激活

如果扩展无法激活 Ruby 环境，请尝试在您的 shell 中手动运行相同的命令，以查看问题是否仅与扩展有关。用于激活的确切命令将打印到输出选项卡。

尝试手动启动服务器

如果 Ruby 环境似乎已正确激活，但服务器无法启动，请尝试从终端手动启动，命令为：

# Do not use bundle exec
ruby-lsp

手动启动服务器时是否提供了任何额外信息？或者它是否仅在通过扩展启动时失败？

索引

当 Ruby LSP 启动时，它会尝试索引您的代码以及您的依赖项，如配置代码索引中所述。

在极少数情况下，Ruby LSP 会遇到阻止索引完成的错误，这将导致编辑器中的信息不完整。

首先，请确保您使用的是最新版本的 ruby-lsp gem，因为该问题可能已被修复。

要诊断导致问题的特定文件，请运行 ruby-lsp-check。请记录一个问题，以便我们解决它。如果代码不是开源的，请提供一个最小的重现。

同时，您可以配置 Ruby LSP 以忽略特定的 gem 或文件进行索引。

故障排除后

如果在故障排除后 Ruby LSP 仍然无法正确初始化，请在此处报告一个问题，以便我们可以协助解决问题。请记住包括在尝试诊断问题时所采取的步骤。

目录