Rust 開發環境完整教學

Windows 11 + WSL2 + Docker + VSCode

適用情境：在 Windows 上建立原生 Linux Rust 開發環境，搭配 VSCode 完整 debug 支援，並部署至 AWS Lambda。

架構概覽

Windows 11
├── VSCode (Windows App)
│   └── WSL Extension → 連接 WSL2 環境
├── Docker Desktop
│   └── 底層使用 WSL2 運行容器
└── WSL2 (Ubuntu 24.04)
    ├── Rust + cargo + cargo-lambda
    ├── AWS CLI + SAM CLI
    ├── Claude Code CLI
    ├── Node.js (via nvm)
    └── Git + gh CLI

為什麼選 WSL2？

Lambda 跑在 Linux，開發環境與目標環境一致，cross-compile 不需要額外工具
VSCode WSL Extension 支援完整 breakpoint debug
檔案 I/O 速度比 /mnt/c/ 快 3-5 倍
所有 Linux 工具開箱即用

前置需求

需求	最低版本	確認指令
Windows	11 或 10 (Build 19041+)	`winver`
PowerShell	5.1+	`$PSVersionTable`
Docker Desktop	4.48+	Docker Desktop → About
VSCode	最新版	`code --version`

WSL2 安裝與設定

Step 1：確認 WSL2 已安裝

在 PowerShell（系統管理員） 執行：

wsl --version

預期輸出：

WSL 版本: 2.x.x
核心版本: x.x.x

Step 2：安裝 Ubuntu

wsl --install -d Ubuntu

安裝完成後系統會提示設定：

Username：輸入你的 Linux 使用者名稱（小寫英文）
Password：設定密碼（輸入時不會顯示，這是正常的）

Step 3：確認 Ubuntu 版本

# 在 WSL2 Ubuntu 裡執行
lsb_release -a

Step 4：更新系統套件

sudo apt update && sudo apt upgrade -y

Step 5：安裝基本開發工具

sudo apt install -y \
  build-essential \
  curl \
  git \
  unzip \
  pkg-config \
  libssl-dev

Step 6：設定 Git

git config --global user.name "你的名字"
git config --global user.email "你的信箱@example.com"
git config --global init.defaultBranch main

Docker Desktop 整合

確認 Docker 在 WSL2 中可用

# 在 WSL2 Ubuntu 裡執行
docker --version
docker run hello-world

如果出現 permission denied：

sudo usermod -aG docker $USER
# 重新開啟 WSL2 terminal

Docker Desktop 設定

開啟 Docker Desktop → Settings → Resources → WSL Integration：

勾選 Enable integration with my default WSL distro
勾選 Ubuntu

VSCode 設定

Step 1：安裝必要 Extension（在 Windows VSCode 裡）

Extension	ID	用途
WSL	`ms-vscode-remote.remote-wsl`	連接 WSL2
rust-analyzer	`rust-lang.rust-analyzer`	Rust 語言支援
CodeLLDB	`vadimcne.codelldb`	Rust Debug
Even Better TOML	`tamasfe.even-better-toml`	Cargo.toml 支援
GitLens	`eamodio.gitlens`	Git 增強

什麼是「WSL2 終端機」？如何開啟？

WSL2 終端機指的是在 Linux（Ubuntu）環境 裡跑 shell（例如 Bash）的視窗；看到的提示字元像 user@hostname:~$，指令與路徑都是 Linux 語意（~、/、sudo），不是 PowerShell。

常用開啟方式（擇一即可）：

方式	操作
Ubuntu 應用程式	開始選單搜「Ubuntu」→ 開啟
Windows Terminal	開啟 Windows Terminal → 分頁下拉選 Ubuntu（若沒有，先到設定裡新增 WSL 設定檔）
從 PowerShell 進入	在 PowerShell 執行 `wsl` 或 `wsl -d Ubuntu`
已在 VSCode 用 Remote-WSL	連上 WSL 後，終端機 → 新增終端機預設就是該 distro 的 shell

第一次若跳出 Linux 帳密登入，代表你已進入 WSL2，不是 Windows 的 C:\。

Step 2：從 WSL2 開啟 VSCode（需先有專案資料夾）

code . 的意義是：用目前目錄當成工作區 在 Windows 開啟 VSCode，並透過 Remote-WSL 掛到 WSL2。因此目錄必須已存在；本文件的閱讀順序裡，完整的 Lambda 專案要到後面第一個 Rust Lambda 專案才用 gh repo create 等方式建立。

建議流程：先照順序完成 Rust 開發環境，再完成「第一個 Rust Lambda 專案」的建庫步驟；在 WSL2 終端機裡 cd 進專案根目錄（gh repo create ... --clone 預設會在目前目錄下出現 hello-lambda-rust，故常見路徑為 ~/hello-lambda-rust；若你改在 ~/projects 下執行建庫，則為 ~/projects/hello-lambda-rust），然後再執行下面的 code .。
若只想先確認 VSCode ↔ WSL 能連線：可在 WSL2 終端機建立空資料夾測試，不一定要先有 Rust 專案：

mkdir -p ~/projects/vscode-wsl-smoke-test
cd ~/projects/vscode-wsl-smoke-test
code .

附註：若你在 Windows 已安裝 VSCode 並勾選「將 code 加入 PATH」，在 WSL2 裡通常也能執行 code；若指令找不到，請在 Windows 端重新安裝 VSCode 並啟用 Shell Command: Install 'code' command in PATH。

# 實際開發時：在 WSL2 終端機進入「已存在的」專案根目錄後執行
# 例：Lambda 專案建在本機家目錄時
cd ~/hello-lambda-rust

# 在 Windows 開啟 VSCode，但連接到 WSL2（Remote-WSL）
code .

VSCode 左下角會顯示：

><WSL: Ubuntu

Step 3：設定 Debug（launch.json）

在專案根目錄建立 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Lambda Handler",
      "cargo": {
        "args": ["build", "--bin", "bootstrap", "--package", "hello-lambda-rust"],
        "filter": {
          "name": "bootstrap",
          "kind": "bin"
        }
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    },
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Unit Tests",
      "cargo": {
        "args": ["test", "--no-run", "--lib"],
        "filter": {
          "name": "hello-lambda-rust",
          "kind": "lib"
        }
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  ]
}

Step 4：設定 rust-analyzer（settings.json）

在 .vscode/settings.json：

{
  "rust-analyzer.cargo.buildScripts.enable": true,
  "rust-analyzer.procMacro.enable": true,
  "editor.formatOnSave": true,
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  }
}