在 Visual Studio Code 中使用 Ruby

Ruby 是一門動態、開源的程式語言，以其簡潔和高生產力而聞名。Ruby 的哲學中，表達力強且優雅的語法旨在讓開發者感到快樂。它常被用於各類 Web 開發框架，以及指令碼編寫，能讓開發者在構建原型時快速迭代。

本主題將詳細介紹如何在 Visual Studio Code 中，使用 Ruby LSP 擴充功能來設置與使用 Ruby。

Ruby extension banner

安裝

透過版本管理工具安裝 Ruby

雖然某些作業系統（如 macOS 和部分 Linux 發行版）預設已安裝 Ruby，但我們建議使用版本管理工具來取得更新版本的 Ruby，例如 macOS 和 Linux 上的 rbenv，以及 Windows 上的 rbenv。請依照您作業系統平台的安裝指南進行操作。

注意：如同在電腦上安裝任何新工具集一樣，您需要確保重新啟動終端機（Terminal）/命令提示字元（Command Prompt）以及 VS Code 實例，以便讓系統使用您作業系統 PATH 變數中更新後的工具集路徑。

在 VS Code 中安裝 Ruby LSP 擴充功能

您可以直接從 VS Code 內部的擴充功能檢視（Extensions view，快速鍵 ⇧⌘X (Windows, Linux Ctrl+Shift+X)）搜尋「Ruby LSP」並進行安裝。

Ruby LSP extension in the Extensions view

我們將在本主題中討論 Ruby LSP 的許多功能，但您也可以參考該擴充功能的說明文件和 GitHub 儲存庫。

檢查安裝結果

安裝後，請查看狀態列（Status Bar）中的語言狀態項目，以確認 Ruby LSP 伺服器的狀態。如果已正確設定版本管理工具，它應該會顯示適合您專案的正確 Ruby 版本。伺服器狀態應顯示為「啟動中」或「執行中」，而不應顯示「錯誤」。

Ruby LSP language status center

該擴充功能會自動產生一個 .ruby-lsp 資料夾，其中包含自訂的 bundle，裡面含有 ruby-lsp 這個語言伺服器 gem。基本上不需要額外配置。

預設情況下，該擴充功能會嘗試自動偵測您使用的 Ruby 版本管理工具，並據此使用正確的版本與路徑。如果您想要自訂此行為，請在您的使用者設定（Settings）中進行以下配置：

{
  "rubyLsp.rubyVersionManager": {
    "identifier": "rbenv"
  }
}

該擴充功能會定期嘗試自動更新 ruby-lsp 語言伺服器 gem；如果您想強制更新，請使用命令面板（Command Palette，快速鍵 ⇧⌘P (Windows, Linux Ctrl+Shift+P)）執行 Ruby LSP: Update language server gem。

如果您遇到任何問題，請參閱疑難排解（Troubleshooting）以了解下一步操作。

主要功能

導覽與 IntelliSense

Ruby LSP 提供了多項與導覽及 IntelliSense 相關的功能，例如：前往定義（Go to Definition）、懸停預覽（Hover）、工作區符號（Workspace Symbol）、文件符號（Document Symbol）、自動完成（Completion）以及簽章說明（Signature Help）。

若要進一步了解如何在 VS Code 中快速瀏覽原始碼，請參考程式碼導覽（Code Navigation）。

內嵌提示 (Inlay hints)

Ruby LSP 能夠顯示關於程式碼中隱式（implicit）或推斷值（inferred values）的實用資訊。在下方的範例中，您可以看到在空的 rescue 區塊中，StandardError 被顯示為隱式處理的例外類別。

Ruby program with inlay hints displayed

雖然內嵌提示（Inlay Hints）有助於理解程式碼，但您也可以透過 Editor > Inlay Hints: Enabled 設定（ editor.inlayHints.enabled 在 VS Code 中開啟在 VS Code Insiders 中開啟）來停用此功能，或者使用下列設定僅針對 Ruby LSP 停用此功能：

"rubyLsp.enabledFeatures": {
    "inlayHint": false,
}

語意語法高亮

Ruby LSP 能夠利用語意語法高亮（Semantic syntax highlighting）與樣式設定，這得益於它對專案原始碼的深入理解。

例如，它可以高亮顯示：

方法呼叫，並能與區域變數區分開來。
區域引數（例如方法、區塊或 Lambda 引數），並在它們所屬的作用域內保持一致的高亮顯示。

Ruby LSP semantic highlighting

注意：此螢幕截圖使用了 Ruby 擴充套件包中包含的 Spinel 主題。主題必須使用 Ruby LSP 提供的資訊，才能為 Ruby 檔案提供豐富的高亮顯示效果。

若要使用此功能，編輯器必須啟用語意高亮顯示。

"editor.semanticHighlighting.enabled": true,

Linting 與格式化

預設情況下，Ruby LSP 透過與 RuboCop 的整合來提供 Linting 和格式化功能。您可以使用 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I)，或透過命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）以及編輯器中的右鍵內容選單，執行 Format Document 指令來格式化您的 Ruby 檔案。

如果您的專案未使用 RuboCop，Ruby LSP 將會使用 SyntaxTree 來格式化檔案。

Linting a Ruby file

您也可以在每次儲存時自動執行格式化（Editor: Format On Save），以確保在工作時您的 Ruby 程式碼始終保持正確的格式。要達成此目的，您必須啟用「儲存時格式化」功能。

"editor.formatOnSave": true

Ruby LSP 擴充功能還提供了一些便利的輸入時格式化（Format on type）功能。例如，它會自動續接註解行，並自動補齊 end 標記、管線符號（pipes）或字串插補的大括號。若要使用此功能，請確保編輯器已啟用該設定：

"editor.formatOnType": true

快速修復

當 Linter 在原始碼中發現錯誤或警告時，Ruby LSP 通常會提供建議的「快速修復」（也稱為程式碼動作 Code Actions），這些功能可透過編輯器中的燈泡圖示懸停來存取。您也可以快速開啟可用的快速修復，請按 ⌘. (Windows, Linux Ctrl+.)。

Quick Fixes for linting violations

此外，Code Action Widget: Include Nearby Quick Fixes（ editor.codeActionWidget.includeNearbyQuickFixes 在 VS Code 中開啟在 VS Code Insiders 中開啟）是一項預設啟用的設定，這會允許您無論游標在哪一行，只要按下 ⌘. (Windows, Linux Ctrl+.) (指令 ID editor.action.quickFix)，即可啟動該行最近的快速修復。

此指令會反白顯示將透過快速修復進行重構或修復的原始碼。一般的程式碼動作與非修復性的重構仍然可以在游標位置啟動。

重構

除了快速修復之外，Ruby LSP 還透過程式碼動作提供重構選項。例如，它可以一鍵將 Ruby 表達式提取為區域變數。

Refactor extract to variable

偵錯

Ruby LSP 擴充功能支援使用 `debug` gem（Ruby 官方偵錯工具）進行偵錯。或者，開發者也可以安裝 VS Code RDBG 擴充功能來獲得偵錯功能。

以下文件適用於 Ruby LSP 的偵錯用戶端。請參閱 RDBG 的 README 以了解如何設定的說明。

偵錯測試（Debugging tests）

Ruby LSP 在單元測試上方新增了 CodeLens 按鈕，讓您能夠在「測試總管（Test Explorer）」中執行測試案例、在新的終端機中執行，或啟動偵錯工具。對於這些功能，無須額外配置。

Test running code lenses

透過啟動任務進行偵錯

若要透過啟動任務（Launch tasks）使用偵錯工具，您需要在 launch.json 檔案中建立偵錯配置。該配置允許您設定要執行的程式。

為 Ruby 程式建立 launch.json：

在「偵錯檢視（Debug view）」（⇧⌘D (Windows, Linux Ctrl+Shift+D)）中，選取 create a launch.json file 連結。
這會顯示一個包含多個預設啟動配置類型的下拉選單。您可以選擇第一個選項，我們之後可以再新增更多配置。
我們現在可以編輯建立好的 .vscode/launch.json 檔案，以新增更多用於偵錯 Ruby 程式的啟動方式。

範例

{
  "version": "0.2.0",
  "configurations": [
    // Launch the debugger for any given program. In this case, it will run the current file using Ruby
    {
      "type": "ruby_lsp",
      "name": "Debug",
      "request": "launch",
      "program": "ruby ${file}"
    },
    // Launch the debugger for the current test file
    {
      "type": "ruby_lsp",
      "request": "launch",
      "name": "Debug test file",
      "program": "ruby -Itest ${relativeFile}"
    },
    // Attach the debugger client to an existing Ruby process that has already been launched with the debugger
    // server
    {
      "type": "ruby_lsp",
      "request": "attach",
      "name": "Attach to existing server"
    }
  ]
}

新增啟動配置後，我們可以透過設定中斷點並執行啟動任務來偵錯 Ruby 程式。

開啟一個 Ruby 檔案，並點擊編輯器左側的裝訂槽（gutter）來設定中斷點。它應該會顯示為一個紅點。
透過在 Run and Debug 下選取所需的任務，並點擊「開始偵錯」按鈕（預設鍵盤快速鍵為 F5）來開始偵錯。

後續步驟

以上是對 VS Code 中 Ruby LSP 擴充功能功能的簡要概述。如需更多資訊，請參閱 Ruby LSP 文件中提供的詳細內容，包括如何調整特定的 VS Code 編輯器配置。

若要隨時掌握 Ruby LSP 擴充功能的最新功能/錯誤修正，請參閱該單一儲存庫（monorepo）的發行頁面（Releases），其中包含了伺服器和 VS Code 擴充功能的實作更新。

如果您有任何問題或功能需求，歡迎在 Ruby LSP 的 GitHub 儲存庫中提出。

如果您想進一步了解 VS Code，請嘗試這些主題：

基本編輯 - 快速介紹 VS Code 編輯器的基本功能。
安裝擴充功能 - 了解在Marketplace 中還有哪些其他擴充功能可用。
程式碼導覽 - 在原始碼中快速移動。

4/8/2026