編輯

在WSL中進行開發

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code WSL 擴充套件允許您直接從 VS Code 中將適用於 Linux 的 Windows 子系統 (WSL) 用作全職開發環境。您可以在基於 Linux 的環境中進行開發，使用 Linux 專用的工具鏈和實用程式，並在 Windows 的舒適環境中執行和除錯基於 Linux 的應用程式。

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

WSL Architecture

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

入門

注意：閱讀本主題後，您可以透過入門 WSL 教程開始使用。

安裝

要開始使用，您需要

安裝適用於 Linux 的 Windows 子系統以及您首選的 Linux 發行版。

注意： WSL 1 對於某些型別的開發存在一些已知限制。此外，由於擴充套件內部原生原始碼中的 glibc 依賴項，安裝在 Alpine Linux 中的擴充套件可能無法工作。有關詳細資訊，請參閱遠端開發和 Linux 文章。
在 Windows 端（而不是 WSL 中）安裝 Visual Studio Code。

注意： 在安裝過程中，當提示您“選擇附加任務”時，請務必勾選“新增到 PATH”選項，以便您可以使用 code 命令輕鬆地在 WSL 中開啟資料夾。
安裝 WSL 擴充套件。如果您計劃在 VS Code 中使用其他遠端擴充套件，您可以選擇安裝遠端開發擴充套件包。

開啟遠端資料夾或工作區

從 WSL 終端

在 VS Code 中開啟適用於 Linux 的 Windows 子系統內的資料夾與從命令提示符或 PowerShell 開啟 Windows 資料夾非常相似。

開啟 WSL 終端視窗（使用開始選單項或從命令提示符/PowerShell 中鍵入 wsl）。
導航到您想在 VS Code 中開啟的資料夾（包括但不限於 Windows 檔案系統掛載點，例如 /mnt/c）。
在終端中輸入 code .。第一次這樣做時，您應該會看到 VS Code 正在獲取在 WSL 中執行所需的元件。這應該只需要很短的時間，並且只需要一次。

注意： 如果此命令不起作用，您可能需要重新啟動終端，或者您在安裝時沒有將 VS Code 新增到路徑中。
稍後，一個新的 VS Code 視窗將出現，您會看到一個通知，表示 VS Code 正在 WSL 中開啟資料夾。

VS Code 現在將繼續在 WSL 中配置自身，並隨時向您更新進度。
完成後，您現在會在左下角看到一個 WSL 指示器，您可以像往常一樣使用 VS Code！

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

從 VS Code

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

啟動 VS Code。
按 F1，為預設發行版選擇 WSL: 連線到 WSL，或為特定發行版選擇 WSL: 使用發行版連線到 WSL。
使用“檔案”選單開啟您的資料夾。

如果您已經打開了一個資料夾，您還可以使用 WSL: 在 WSL 中重新開啟資料夾 命令。系統會提示您選擇要使用的發行版。

如果您在一個 WSL 視窗中，並想在本地視窗中開啟當前輸入，請使用 WSL: 在 Windows 中重新開啟。

從 Windows 命令提示符

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

code --remote wsl+<發行版名稱> <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

注意： 如果您是擴充套件作者，並且您的擴充套件無法正常工作或安裝在錯誤的位置，請參閱支援遠端開發以獲取詳細資訊。

需要遠端執行的本地擴充套件在“本地 - 已安裝”類別中會顯示為灰色並停用。選擇“安裝”以在您的遠端主機上安裝擴充套件。

Disabled Extensions w/Install Button

您還可以透過轉到“擴充套件”檢視並使用“本地 - 已安裝”標題欄右側的雲按鈕選擇“在 WSL: {名稱} 中安裝本地擴充套件”來在 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) 執行 首選項：開啟遠端設定 命令或在設定編輯器中選擇遠端選項卡來設定 WSL 特定設定。這些設定將在您每次在 WSL 中開啟資料夾時覆蓋您已有的任何本地設定。

高階：環境設定指令碼

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

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

檢查 WSL 日誌 (WSL: 顯示日誌) 以獲取輸出和錯誤。

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

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

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

提示： 轉到 設定 > 資源 > WSL 整合 併為您將使用的 WSL 發行版啟用 Docker 整合。
如果您尚未安裝，請安裝開發容器擴充套件以及 WSL 擴充套件。
接下來，像往常一樣在 WSL 中開啟您的原始碼資料夾。
一旦您的資料夾在 WSL 中開啟，從命令面板 (F1) 中選擇 開發容器：在容器中重新開啟。
如果資料夾中沒有 .devcontainer/devcontainer.json 檔案，系統會要求您從可篩選的列表中選擇一個起點，或者選擇一個現有的 Dockerfile 或 Docker Compose 檔案（如果存在）。
VS Code 視窗（例項）將重新載入並開始構建開發容器。進度通知提供狀態更新。
構建完成後，VS Code 將自動連線到容器。您現在可以從容器內部處理您的原始碼。

有關更多資訊，請參閱開發容器文件。

已知限制

本節包含 WSL 常見已知問題的列表。目的不是提供問題的完整列表，而是突出 WSL 中一些常見的問題。

有關與 WSL 相關的活動問題列表，請參閱此處。

在 WSL 1 中嘗試重新命名開啟工作區中的資料夾時，出現 EACCES：許可權被拒絕錯誤

這是 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 錯誤：spawn EACCES（此錯誤的不同變體）	Microsoft/WSL#3886
Webpack HMR 無法工作	Microsoft/WSL#2709
透過 node 訪問 Firebase 在 WSL 上異常慢	Microsoft/WSL#2657

Git 限制

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

容器工具擴充套件限制

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

擴充套件限制

許多擴充套件可以在 WSL 中無需修改即可工作。但是，在某些情況下，某些功能可能需要更改。如果您遇到擴充套件問題，請參閱此處獲取常見問題和解決方案的摘要，您可以在報告問題時向擴充套件作者提及。

此外，在使用基於 Alpine Linux 的發行版時，WSL 中安裝的某些擴充套件可能無法工作，因為擴充套件內部原生程式碼中存在 glibc 依賴項。有關詳細資訊，請參閱使用 Linux 進行遠端開發文章。

常見問題

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

當使用 WSL: 使用發行版連線到 WSL 並且執行的 WSL 版本早於 Windows 10，2019 年 5 月更新 (版本 1903) 時，您將被要求切換 預設發行版，因為 WSL 命令只能在預設發行版上工作，因為它尚不支援 -d 選項。

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

例如

wslconfig /setdefault Ubuntu

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

wslconfig /l

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

某些擴充套件依賴於某些 WSL Linux 發行版的預設安裝中找不到的庫。您可以使用其包管理器將其他庫新增到您的 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 端可能缺少代理設定。

當從 VSCode 外部開啟遠端視窗時，WSL 擴充套件會嘗試在 Windows 端下載 VSCode 伺服器。因此，它使用 Windows 端的代理配置

繼承自作業系統設定
如 Visual Studio Code 中的網路連線所述

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

wget 代理設定：https://stackoverflow.com/questions/11211705/how-to-set-proxy-for-wget
手動在伺服器設定指令碼中

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

我可以強制擴充套件在本地/遠端執行嗎？

擴充套件通常設計和測試為僅在本地或遠端執行，而不是兩者都執行。但是，如果擴充套件支援，你可以在 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/客戶端側執行。通常，除非擴充套件文件中另有說明，否則這應該僅用於測試，因為它可能會破壞擴充套件。有關詳細資訊，請參閱支援遠端開發一文。

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

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

問題或反饋

請參閱提示和技巧或常見問題。
在 Stack Overflow 上搜索。
新增功能請求或報告問題。
為我們的文件或VS Code 本身做出貢獻。
請參閱我們的貢獻指南瞭解詳細資訊。

09/11/2025