現已釋出！閱讀關於 11 月新增功能和修復的內容。

在 WSL 中開發

Visual Studio Code WSL 擴充套件可讓您將 Windows Subsystem for Linux (WSL) 作為您全職開發環境，直接從 VS Code 使用。您可以開發基於 Linux 的環境，使用特定於 Linux 的工具鏈和實用程式，並且可以在 Windows 中舒適地執行和除錯基於 Linux 的應用程式。

該擴充套件直接在 WSL 中執行命令和其他擴充套件，因此您可以編輯位於 WSL 或已掛載的 Windows 檔案系統（例如 /mnt/c）中的檔案，而無需擔心路徑問題、二進位制相容性或其他跨作業系統挑戰。該擴充套件將在 WSL 中安裝 VS Code Server；該伺服器獨立於 WSL 中現有的任何 VS Code 安裝。

WSL Architecture

這使得 VS Code 能夠提供 **本地質量的開發體驗** — 包括完整的 IntelliSense（程式碼補全）、程式碼導航和除錯 — **無論您的程式碼託管在哪裡**。

入門

注意：閱讀完本主題後，您可以開始進行入門級的 WSL 教程。

安裝

要開始，您需要

  1. 安裝 Windows Subsystem for Linux 以及您喜歡的 Linux 發行版。

    注意：WSL 1 在某些型別的開發方面確實存在一些 已知限制。此外，由於擴充套件內部的本地原始碼中存在 glibc 依賴項，安裝在 Alpine Linux 上的擴充套件可能無法正常工作。有關詳細資訊，請參閱 Remote Development and Linux 文章。

  2. 在 **Windows** 端安裝 Visual Studio Code（而不是在 WSL 中）。

    注意：在安裝過程中，當提示您 **選擇附加任務** 時，請務必勾選 **新增到 PATH** 選項，以便您可以使用 code 命令輕鬆地在 WSL 中開啟資料夾。

  3. 安裝 WSL 擴充套件。如果您打算在 VS Code 中使用其他遠端擴充套件，您可以選擇安裝 Remote Development 擴充套件包。

開啟遠端資料夾或工作區

從 WSL 終端

在 VS Code 中開啟 Windows Subsystem for Linux 中的資料夾，與從命令提示符或 PowerShell 開啟 Windows 資料夾非常相似。

  1. 開啟一個 **WSL 終端視窗**（使用開始選單項或從命令提示符/PowerShell 輸入 wsl）。

  2. 導航到您想在 VS Code 中開啟的資料夾（包括但不限於 Windows 檔案系統掛載點，如 /mnt/c）

  3. 在終端中輸入 **code .**。首次執行此操作時，您應該會看到 VS Code 正在獲取在 WSL 中執行所需的元件。這隻需要很短的時間，並且只需要執行一次。

    注意：如果此命令不起作用，您可能需要重新啟動終端，或者在安裝 VS Code 時未將其新增到您的 PATH。

  4. 片刻之後，一個新的 VS Code 視窗將出現，您將看到一個通知，提示 VS Code 正在 WSL 中開啟資料夾。

    WSL Starting notification

    VS Code 現在將繼續在 WSL 中進行自我配置，並在進度時向您提供最新資訊。

  5. 完成後，您將在左下角看到一個 WSL 指示符，並且可以像平常一樣使用 VS Code！

    WSL Status Bar Item

就是這樣！您在此視窗中執行的所有 VS Code 操作都將在 WSL 環境中執行，從編輯和檔案操作到除錯、使用終端等等。

從 VS Code

或者，您可以直接從 VS Code 開啟 WSL 視窗

  1. 啟動 VS Code。
  2. 按 F1，選擇 **WSL: Connect to WSL**（針對預設發行版）或 **WSL: Connect to WSL using Distro**（針對特定發行版）。
  3. 使用“檔案”選單開啟您的資料夾。

如果您已經打開了一個資料夾，您也可以使用 **WSL: Reopen Folder in WSL** 命令。您將被提示選擇要使用的發行版。

如果您處於 WSL 視窗中並希望在本地視窗中開啟當前輸入，請使用 **WSL: Reopen in Windows**。

從 Windows 命令提示符

要直接從 Windows 提示符開啟 WSL 視窗，請使用 --remote 命令列引數

code --remote wsl+<distro name> <path in WSL>

例如：code --remote wsl+Ubuntu /home/jim/projects/c

我們需要猜測輸入路徑是檔案還是資料夾。如果它有副檔名，則將其視為檔案。

要強制開啟資料夾，請在路徑末尾新增斜槓，或者使用

code --folder-uri vscode-remote://wsl+Ubuntu/home/ubuntu/folder.with.dot

要強制開啟檔案，請新增 --goto 或使用

code --file-uri vscode-remote://wsl+Ubuntu/home/ubuntu/fileWithoutExtension

使用 Git

如果您在 WSL 和 Windows 中都使用同一個儲存庫，請確保設定一致的換行符。有關詳細資訊，請參閱 技巧與竅門。

您還可以透過配置 WSL 使用 Windows Git 憑據管理器來避免輸入密碼。有關詳細資訊，請參閱 技巧與竅門。

管理擴充套件

VS Code 在兩個位置之一執行擴充套件：本地（UI/客戶端側），或在 WSL 中。雖然影響 VS Code UI 的擴充套件（如主題和片段）是本地安裝的，但大多數擴充套件將駐留在 WSL 中。

如果您從“擴充套件”檢視安裝擴充套件，它將自動安裝在正確的位置。安裝後，您可以根據類別分組來判斷擴充套件的安裝位置。將有一個 **本地 - 已安裝** 類別，以及一個用於 WSL 的類別。

Workspace Extension Category

Local Extension Category

注意：如果您是擴充套件作者，並且您的擴充套件未能正常工作或安裝在錯誤的位置，請參閱 Supporting Remote Development 以獲取詳細資訊。

實際需要遠端執行的本地擴充套件將在 **本地 - 已安裝** 類別中顯示為灰色且停用。選擇 **安裝** 以在遠端主機上安裝擴充套件。

Disabled Extensions w/Install Button

您還可以透過轉到“擴充套件”檢視並選擇 **Install Local Extensions in WSL: {Name}**（使用 **本地 - 已安裝** 標題欄右側的雲按鈕）來在 WSL 中安裝所有本地安裝的擴充套件。這將顯示一個下拉列表，您可以在其中選擇要安裝在 WSL 例項中的本地已安裝擴充套件。

Install all extensions

在 WSL 中開啟終端

從 VS Code 在 WSL 中開啟終端非常簡單。一旦資料夾在 WSL 中開啟，您在 VS Code 中開啟的 **任何終端視窗**（終端 > 新建終端）將自動在 WSL 中執行，而不是在本地執行。

您還可以從同一個終端視窗使用 code 命令列來執行多項操作，例如在 WSL 中開啟新檔案或資料夾。輸入 code --help 以檢視命令列可用的選項。

Using the code CLI

在 WSL 中除錯

一旦您在 WSL 中打開了一個資料夾，您就可以像在本地執行應用程式一樣使用 VS Code 的偵錯程式。例如，如果您在 launch.json 中選擇了一個啟動配置並開始除錯（F5），應用程式將在遠端主機上啟動並將偵錯程式附加到它。

有關在 .vscode/launch.json 中配置 VS Code 除錯功能的詳細資訊，請參閱除錯文件。

WSL 特定設定

當您在 WSL 中開啟資料夾時，VS Code 的本地使用者設定也會被重用。雖然這可以保持您的使用者體驗一致，但您可能希望在本地計算機和 WSL 之間更改其中一些設定。幸運的是，一旦您連線到 WSL，您還可以透過從命令面板（F1）執行 **Preferences: Open Remote Settings** 命令，或在設定編輯器中選擇 **Remote** 選項卡來設定 WSL 特定的設定。當您在 WSL 中開啟資料夾時，這些設定將覆蓋您現有的任何本地設定。

高階：環境設定指令碼

當 VS Code Remote 在 WSL 中啟動時，不會執行任何 shell 啟動指令碼。這樣做是為了避免與為 shell 調整的啟動指令碼出現問題。如果您想執行其他命令或修改環境，可以在設定指令碼 ~/.vscode-server/server-env-setup（Insider 版本：~/.vscode-server-insiders/server-env-setup）中完成。如果存在，該指令碼將在伺服器啟動之前被處理。

指令碼必須是有效的 Bourne shell 指令碼。請注意，無效的指令碼將阻止伺服器啟動。如果您最終得到一個阻止伺服器啟動的指令碼，您將不得不使用常規的 WSL shell 並刪除或重新命名設定指令碼。

檢查 WSL 日誌（**WSL: Show Log**）以獲取輸出和錯誤。

高階：在容器中開啟 WSL 2 資料夾

如果您正在使用 WSL 2 和 Docker Desktop 的 WSL 2 後端，您可以使用 Dev Containers 擴充套件來處理儲存在 WSL 中的原始碼！只需按照以下步驟操作：

  1. 如果尚未安裝，請 安裝並設定 Docker Desktop 的 WSL 2 支援。

    提示：轉到 **設定 > 資源 > WSL 整合**，並啟用 Docker 與您將使用的 WSL 發行版的整合。

  2. 如果尚未安裝，請安裝 Dev Containers 擴充套件以及 WSL 擴充套件。

  3. 接下來，像往常一樣 在 WSL 中開啟您的原始碼資料夾。

  4. 資料夾在 WSL 中開啟後，從命令面板（F1）選擇 **Dev Containers: Reopen in Container**。

  5. 如果資料夾中沒有 .devcontainer/devcontainer.json 檔案，系統將要求您從可過濾的列表中選擇一個起點，或者選擇一個現有的 Dockerfile 或 Docker Compose 檔案（如果存在）。

    Select a node dev container definition

  6. VS Code 視窗（例項）將重新載入並開始構建開發容器。進度通知將提供狀態更新。

    Dev Container Progress Notification

  7. 構建完成後，VS Code 將自動連線到容器。現在您可以從容器內部處理您的原始碼。

有關更多資訊，請參閱 Dev Containers 文件。

已知限制

本節包含 WSL 常見已知問題的列表。意圖不是提供完整的問題列表，而是要強調一些在使用 WSL 時常見的使用者遇到的問題。

請在此處檢視 與 WSL 相關的活動問題列表。

我在 WSL 1 中開啟的工作區中重新命名資料夾時遇到 EACCES: permission denied 錯誤

這是 WSL 檔案系統實現中的一個已知問題（Microsoft/WSL#3395，Microsoft/WSL#1956），由 VSCode 啟用的檔案監視器引起。該問題將在 WSL 2 中得到修復。

為避免此問題，請將 remote.WSL.fileWatcher.polling 設定為 true。但是，對於大型工作區，基於輪詢的檔案監視會影響效能。

對於大型工作區，您需要增加輪詢間隔：remote.WSL.fileWatcher.pollingInterval 並控制被監視的資料夾：files.watcherExclude。

WSL 2 沒有這個檔案監視器問題，也不會受到新設定的影響。

WSL 1 中的 Golang

問題 現有問題
Delve 偵錯程式在 WSL 下無法正常工作 go-delve/delve#810，Microsoft/vscode-go#926

WSL 1 中的 Node.js

問題 現有問題
NodeJS Error: spawn EACCES（此錯誤的變種） Microsoft/WSL#3886
Webpack HMR 無法正常工作 Microsoft/WSL#2709
Firebase 透過 node 在 WSL 上使用起來異常緩慢 Microsoft/WSL#2657

Git 限制

如果你使用 SSH 克隆 Git 倉庫，並且你的 SSH 金鑰有密碼短語，VS Code 的拉取和同步功能在遠端執行時可能會掛起。請使用不帶密碼短語的 SSH 金鑰，使用 HTTPS 克隆，或者從命令列執行 git push 來解決此問題。

容器工具擴充套件限制

雖然 Container Tools 擴充套件可以在遠端和本地執行，但如果它已經在本地安裝，則在本地解除安裝之前，您將無法在遠端 SSH 主機上安裝它。我們將在未來的 VS Code 版本中解決此問題。

擴充套件限制

許多擴充套件無需修改即可在 WSL 中執行。但是，在某些情況下，某些功能可能需要更改。如果您遇到擴充套件問題，請在此處檢視 常見問題和解決方案摘要，您可以在報告問題時提供給擴充套件作者。

此外，在使用 Alpine Linux 發行版時，安裝在 WSL 中的某些擴充套件可能無法正常工作，因為擴充套件內部的原生代碼中存在 glibc 依賴項。有關詳細資訊，請參閱 Remote Development with Linux 文章。

常見問題

為什麼要求我更改預設發行版？

當使用 **WSL: Connect to WSL using Distro** 並在早於 Windows 10 五月更新 (1903 版本) 的 Windows 上執行時，系統會要求您切換 **預設發行版**，因為 WSL 命令只能在預設發行版上執行，因為它還不支援 -d 選項。

您始終可以使用 wslconfig.exe 手動切換預設發行版。

例如

wslconfig /setdefault Ubuntu

您可以使用以下命令檢視已安裝的發行版

wslconfig /l

我看到關於缺少庫或依賴項的錯誤

某些擴充套件依賴於某些 WSL Linux 發行版的標準安裝中找不到的庫。您可以使用發行版的包管理器向其新增其他庫。對於基於 Ubuntu 和 Debian 的發行版，請執行 sudo apt-get install <package> 來安裝所需的庫。有關其他安裝詳情，請查閱您的擴充套件或執行時文件。

WSL 擴充套件的連線要求是什麼？

WSL 擴充套件和 VS Code Server 需要出站 HTTPS（埠 443）連線到

  • update.code.visualstudio.com
  • vscode.download.prss.microsoft.com
  • marketplace.visualstudio.com
  • *.gallerycdn.vsassets.io (Azure CDN)

某些擴充套件（如 C#）從 download.microsoft.com 或 download.visualstudio.microsoft.com 下載次要依賴項。其他擴充套件（如 Visual Studio Live Share）可能有額外的連線要求。如果您遇到問題，請諮詢擴充套件文件瞭解詳情。

伺服器和 VS Code 客戶端之間的所有其他通訊都透過隨機的本地 TCP 埠完成。您可以在 網路連線文章 中找到 VS Code 本身需要訪問的位置列表。

我處於代理後面，有連線問題

Windows 或 WSL 端可能缺少代理設定。

當 VS Code 開始一個遠端視窗時，WSL 擴充套件嘗試在 Windows 端下載 VSCode 伺服器。因此，它使用 Windows 端代理配置

當遠端 VSCode 從 WSL 終端啟動時，下載是透過 wget 在 WSL 發行版中完成的。代理設定可以在

伺服器啟動並執行後，將使用“遠端”選項卡中的代理設定。

能否強制擴充套件在本地/遠端執行？

擴充套件通常設計和測試為僅在本地或遠端執行，而不是兩者都執行。但是，如果擴充套件支援，你可以在 settings.json 檔案中強制它在特定位置執行。

例如，以下設定將強制 Container Tools 擴充套件在本地執行，以及 Remote - SSH: Editing Configuration Files 擴充套件在遠端執行，而不是使用它們的預設設定：

"remote.extensionKind": {
    "ms-azuretools.vscode-containers": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

將值設定為 "ui" 而不是 "workspace" 將強制擴充套件在本地 UI/客戶端端執行。通常，這應僅用於測試，除非擴充套件文件另有說明，因為它 **可能會破壞擴充套件**。有關詳細資訊，請參閱 Supporting Remote Development 文章。

作為擴充套件作者，我需要做什麼？

VS Code 擴充套件 API 抽象了本地/遠端細節，因此大多數擴充套件無需修改即可工作。但是，考慮到擴充套件可以使用它們想要的任何節點模組或執行時，有時可能需要進行調整。我們建議你測試你的擴充套件，以確保不需要更新。有關詳細資訊，請參閱支援遠端開發。

問題或反饋

12/10/2025
© . This site is unofficial and not affiliated with Microsoft.