在 Visual Studio Code 中使用 Rust

Rust 是一門功能強大的程式語言，通常用於對效能和正確性有高度要求的系統程式設計。如果您是 Rust 的新手並想了解更多資訊，《Rust 程式語言》(The Rust Programming Language) 線上書籍是一個很好的起點。本主題將詳細介紹如何在 Visual Studio Code 中使用 rust-analyzer 擴充功能來設定並編寫 Rust。

安裝

1. 安裝 Rust

首先，您需要在電腦上安裝 Rust 工具鏈。Rust 是透過 rustup 安裝程式進行安裝的，它支援 Windows、macOS 和 Linux。請遵循適合您作業系統的 rustup 安裝指南，並確保安裝建置與執行 Rust 程式所需的額外工具。

2. 安裝 rust-analyzer 擴充功能

您可以透過 VS Code 內部的擴充功能檢視（⇧⌘X (Windows, Linux Ctrl+Shift+X)）搜尋「rust-analyzer」來找到並安裝該擴充功能。您應該安裝 **發行版本 (Release Version)**。

我們將在本主題中討論許多 rust-analyzer 的功能，但您也可以參考該擴充功能的說明文件：https://rust-analyzer.github.io。

檢查安裝情況

安裝 Rust 後，您可以開啟新的終端機/命令提示字元並輸入以下指令，檢查一切是否安裝正確：

rustc --version

這將輸出 Rust 編譯器的版本。如果您想要更多詳細資訊，可以加入 --verbose 參數。如果您遇到問題，可以參考 Rust 的 安裝指南。

您可以執行以下指令，讓您的 Rust 安裝保持為最新版本：

rustup update

Rust 每 6 週會發布新的穩定版本，因此這是一個很好的習慣。

本機 Rust 說明文件

當您安裝 Rust 時，完整的 Rust 說明文件也會安裝在您的電腦上，您可以透過輸入 rustup doc 來查看。Rust 說明文件（包含 《Rust 程式語言》 和 《Cargo 之書》）將會在您的預設瀏覽器中開啟，讓您在離線時也能繼續學習 Rust。

Hello World

Cargo

當您使用 rustup 安裝 Rust 時，工具鏈會包含 rustc 編譯器、rustfmt 原始碼格式化工具以及 clippy Rust 檢查工具。您還會獲得 Cargo（Rust 的套件管理員），它可以協助下載 Rust 依賴套件並編譯執行 Rust 程式。在處理 Rust 專案時，您會發現幾乎所有事情都會用到 cargo。

Cargo new

建立第一個 Rust 程式的好方法是使用 Cargo 來產生專案架構，輸入 cargo new 即可。這將建立一個簡單的「Hello World」程式以及預設的 Cargo.toml 依賴定義檔。您需要傳遞給 cargo new 您想要建立專案的資料夾路徑。

讓我們建立一個 Hello World 專案。請導航至您想要建立專案的資料夾並輸入：

cargo new hello_world

若要在 VS Code 中開啟新專案，請進入新資料夾並透過 code . 啟動 VS Code。

cd hello_world
code .

cargo new 會建立一個包含 main.rs 原始碼檔案和 Cargo.toml Cargo 資訊清單 檔案的簡單 Hello World 專案。

src\
    main.rs
.gitignore
Cargo.toml

main.rs 包含程式的進入點函式 main()，並使用 println! 將 "Hello, world!" 列印到主控台。

fn main() {
    println!("Hello, world!");
}

這個簡單的 Hello World 程式沒有任何依賴，但您可以在 [dependencies] 下加入 Rust 套件 (crate) 引用。

Cargo build

Cargo 可用於建置您的 Rust 專案。開啟一個新的 VS Code 整合終端機（⌃⇧` (Windows, Linux Ctrl+Shift+`)）並輸入 cargo build。

cargo build

現在您會擁有一個 target\debug 資料夾，其中包含編譯後的輸出，包括一個名為 hello_world.exe 的執行檔。

執行 Hello World

Cargo 也可用於透過 cargo run 來執行您的 Rust 專案。

cargo run

您也可以在終端機中透過輸入 .\target\debug\hello_world 手動執行 hello_world.exe。

IntelliSense

IntelliSense 功能由 Rust 語言伺服器 rust-analyzer 提供，它能提供詳細的程式碼資訊和智慧建議。

當您第一次開啟 Rust 專案時，您可以在狀態列的左下角觀察 rust-analyzer 的進度。為了獲得語言伺服器的完整功能，建議等待 rust-analyzer 完成專案的分析。

內嵌提示 (Inlay hints)

您可能會注意到的第一件事是 rust-analyzer 提供了 內嵌提示 (inlay hints)，會在編輯器中以淺色文字顯示推斷的型別、傳回值和具名參數。

雖然內嵌提示有助於理解程式碼，但您也可以透過 **編輯器 > 內嵌提示：已啟用 (Editor > Inlay Hints: Enabled)** 設定（ editor.inlayHints.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ）來設定此功能。

懸停資訊

將滑鼠懸停在任何變數、函式、型別或關鍵字上，將會顯示該項目的相關資訊，例如文件、簽章等。您也可以跳轉至您自己程式碼或標準 Rust 函式庫中的型別定義。

自動完成

當您在 Rust 檔案中輸入時，IntelliSense 會提供建議的完成項目與參數提示。

語意語法高亮

由於對專案原始碼有深入的理解，rust-analyzer 能夠使用 語意語法高亮 (semantic syntax highlighting) 與樣式設定。例如，您可能已經注意到可變變數 (mutable variables) 在編輯器中會有底線。

能夠快速辨識哪些 Rust 變數是可變的可以幫助您理解原始碼，您也可以透過使用者 設定 中的 VS Code editor.semanticTokenColorCustomizations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來變更樣式。

在 settings.json 中，您可以加入以下內容：

{
  "editor.semanticTokenColorCustomizations": {
    "rules": {
      "*.mutable": {
        "fontStyle": "", // set to empty string to disable underline, which is the default
      },
    }
  },
}

您可以在 rust-analyzer 說明文件的 編輯器功能 (Editor features) 章節中了解更多關於 rust-analyzer 語意語法自訂的資訊。

程式碼導覽

程式碼導航功能可在編輯器的右鍵選單中取得。

• 前往定義 (Go to Definition) F12 - 跳轉至型別定義的原始碼。
• 預覽定義 (Peek Definition) ⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10) - 彈出包含型別定義的預覽視窗。
• 前往參照 (Go to References) ⇧F12 (Windows, Linux Shift+F12) - 顯示該型別的所有參照。
• 顯示呼叫階層 (Show Call Hierarchy) ⇧⌥H (Windows, Linux Shift+Alt+H) - 顯示呼叫某個函式或該函式所呼叫的所有函式。

您可以使用 命令選擇區 (Command Palette) (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中的 前往符號 (Go to Symbol) 指令，透過符號搜尋進行導覽。

• 前往檔案符號 (Go to Symbol in File) - ⇧⌘O (Windows, Linux Ctrl+Shift+O)
• 前往工作區符號 (Go to Symbol in Workspace) - ⌘T (Windows, Linux Ctrl+T)

Linting

Rust 工具鏈包含了由 rustc 和 clippy 提供的 Lint 工具，用於偵測原始碼中的問題。

預設啟用的 rustc linter 可偵測基本的 Rust 錯誤，但您可以使用 clippy 來獲得更多的 Lint 檢查。若要在 rust-analyzer 中啟用 clippy 整合，請將 **Rust-analyzer > Check: Command** (rust-analyzer.check.command) 設定從預設的 check 改為 clippy。現在，當您儲存檔案時，rust-analyzer 擴充功能將會執行 cargo clippy，並直接在編輯器和「問題」面板中顯示 clippy 的警告與錯誤。

快速修復

當 linter 在您的原始碼中發現錯誤與警告時，rust-analyzer 通常可以提供建議的快速修復 (Quick Fixes，也稱為程式碼動作)，這些動作可以透過懸停在編輯器中的燈泡圖示來取得。您可以透過 ⌘. (Windows, Linux Ctrl+.) 快速開啟可用的快速修復。

此外，程式碼動作視窗：包含附近的快速修復 (Code Action Widget: Include Nearby Quick Fixes)（ editor.codeActionWidget.includeNearbyQuickFixes 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ）是一項預設啟用的設定，這會讓您無論游標在哪一行，只要按下 ⌘. (Windows, Linux Ctrl+.) (指令 ID editor.action.quickFix)，就能啟動該行最接近的快速修復。

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

重構

由於 rust-analyzer 對您的原始碼有語意理解能力，它還能跨 Rust 檔案提供智慧重新命名。將游標移至變數上，從右鍵選單、指令面板或按下 F2 選擇 **重新命名符號 (Rename Symbol)** 即可。

rust-analyzer 擴充功能還支援其他程式碼重構與程式碼產生功能，該擴充功能稱之為 輔助功能 (Assists)。

以下僅列出部分可用的重構功能：

• 將 if 陳述式轉換為防禦性 return
• 內聯變數 (Inline variable)
• 擷取函式 (Extract function)
• 新增回傳型別
• 新增匯入 (Add import)

格式化

Rust 工具鏈包含一個格式化工具 rustfmt，可以將您的原始碼格式化以符合 Rust 約定。您可以使用 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I)，或從指令面板或編輯器的右鍵選單中執行 **格式化文件 (Format Document)** 指令來格式化您的 Rust 檔案。

您也可以選擇在每次儲存 (編輯器：儲存時格式化) 或貼上 (貼上時格式化) 時執行格式化工具，讓您的 Rust 程式碼在開發過程中自動保持正確的格式。

偵錯

rust-analyzer 擴充功能支援在 VS Code 內部對 Rust 進行除錯。

安裝除錯支援

若要開始除錯，您首先需要安裝以下其中一個支援除錯功能的語言擴充功能：

• Microsoft C++ (ms-vscode.cpptools) – 在 Windows 上
• CodeLLDB (vadimcn.vscode-lldb) – 在 macOS/Linux 上

如果您忘記安裝這些擴充功能，當您嘗試啟動除錯工作階段時，rust-analyzer 將會提供通知並附上前往 VS Code Marketplace 的連結。

使用 Rust Analyzer: Debug

rust-analyzer 擴充功能透過指令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中的 **Rust Analyzer: Debug** 指令，以及編輯器中的 **Run|Debug** CodeLens 提供基本的除錯支援。

讓我們除錯之前建立的 Hello World 程式。首先，我們要在 main.rs 中設定一個中斷點。

1. 您需要啟用 **除錯：允許在任何地方設定中斷點 (Debug: Allow Breakpoints Everywhere)** 設定，您可以在設定編輯器（⌘, (Windows, Linux Ctrl+,)）中搜尋「everywhere」來找到它。

   

2. 開啟 main.rs 並點擊編輯器左側的裝訂線，在 println! 這一行設定一個中斷點。它應該會顯示為一個紅點。

   

3. 若要開始除錯，請使用 **Rust Analyzer: Debug** 指令，或選擇 main() 上方的 **Debug** CodeLens。

   

後續步驟

以上是關於 VS Code 中 rust-analyzer 擴充功能功能的簡要概述。更多資訊請參閱 rust-analyzer 擴充功能 使用者手冊 中提供的詳細資料，包含如何調整特定的 VS Code 編輯器 設定。

若要掌握 rust-analyzer 擴充功能的最新功能與錯誤修復資訊，請參閱 CHANGELOG。您也可以在擴充功能檢視的 **安裝** 下拉選單中安裝 rust-analyzer **預發行版本 (Pre-Release Version)** 來體驗新功能與修復。

如果您有任何問題或功能請求，請隨時在 rust-analyzer 擴充功能的 GitHub 儲存庫 中提出。

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

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

常見問題

連結器錯誤

如果您在嘗試建置 Rust 程式時看到類似 "error: linker `link.exe` not found" 的連結器錯誤，可能是缺少了必要的 C/C++ 工具鏈。根據您的平台，您需要安裝一個包含 C/C++ 連結器的工具鏈，以便合併 Rust 編譯器的輸出。

Windows

在 Windows 上，您還需要安裝 Microsoft C++ Build Tools 以獲得 C/C++ 連結器 link.exe。執行 Visual Studio 安裝程式時，請務必選擇 **使用 C++ 的桌面開發 (Desktop Development with C++ )**。

macOS

您可能需要在終端機中執行 xcode-select --install 來安裝 XCode 工具鏈。

Linux

您可能需要在終端機中執行 sudo apt-get install build-essential，透過 build-essential 套件安裝 GCC 工具鏈。

如需進一步的疑難排解建議，請參考 Rust 安裝 指南。