🚀 在 VS Code 中免費取得 ！

在 WSL 中開發

Visual Studio Code WSL 擴充功能可讓您直接從 VS Code 使用 Windows Subsystem for Linux (WSL) 作為您的全職開發環境。您可以在以 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 中的擴充功能可能無法運作。請參閱 遠端開發和 Linux 文章以取得詳細資訊。

  2. 在 Windows 端 (而非 WSL) 安裝 Visual Studio Code。

    注意： 當在安裝期間提示您選取其他工作時，請務必勾選新增至 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 時未將其新增至路徑。

  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：連線到 WSL 以使用預設發行版本，或選取 WSL：使用發行版本連線到 WSL 以使用特定發行版本。
  3. 使用 [檔案] 功能表開啟您的資料夾。

如果您已開啟資料夾，您也可以使用 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 內部的原始碼！只要依照下列步驟即可

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

    提示： 前往 [設定] > [資源] > [WSL 整合]，並啟用您將使用的 WSL 發行版本的 Docker 整合。

  2. 如果您尚未執行，請安裝 開發容器 擴充功能以及 WSL 擴充功能。

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

  4. 一旦您的資料夾在 WSL 中開啟，請從 [命令面板] (F1) 選取 [開發容器：在容器中重新開啟]。

  5. 如果資料夾中沒有 .devcontainer/devcontainer.json 檔案，系統會要求您從可篩選的清單或現有的 Dockerfile 或 Docker Compose 檔案 (如果有的話) 中選取起點。

    Select a node dev container definition

  6. VS Code 視窗 (執行個體) 將會重新載入並開始建置開發容器。進度通知會提供狀態更新。

    Dev Container Progress Notification

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

如需詳細資訊，請參閱 開發容器文件。

已知限制

本節包含 WSL 常見已知問題的清單。目的不是提供完整的問題清單，而是重點說明 WSL 中常見的一些問題。

如需與 WSL 相關的作用中問題清單，請參閱此處。

我看到 EACCES：嘗試在 WSL 1 中重新命名開啟的工作區中的資料夾時，發生權限遭拒錯誤

這是 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
Firebase 透過節點在 WSL 上速度慢到無法使用 Microsoft/WSL#2657

Git 限制

如果您使用 SSH 複製 Git 存放庫，而且您的 SSH 金鑰有密碼，則 VS Code 的提取和同步功能在遠端執行時可能會停止回應。請使用沒有密碼的 SSH 金鑰、使用 HTTPS 複製，或從命令列執行 git push 以解決此問題。

Docker 擴充功能限制

雖然 Docker 擴充功能可以遠端和本機執行，但如果它已在本機安裝，您將無法在遠端 SSH 主機上安裝，除非先在本機解除安裝。我們將在未來的 VS Code 版本中解決此問題。

擴充功能限制

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

此外，使用以 Alpine Linux 為基礎的發行版本時，在 WSL 中安裝的某些擴充功能可能無法運作，因為擴充功能內部的原生程式碼中存在 glibc 依賴性。如需詳細資訊，請參閱 遠端開發與 Linux 文章。

常見問題

為何系統要求我變更預設發行版本？

當使用 [WSL：使用發行版本連線到 WSL] 且在 Windows 10 2019 年 5 月更新 (版本 1903) 之前的 WSL 上執行時，系統會要求您切換預設發行版本，因為 WSL 命令只能在預設發行版本上運作，因為它尚不支援 -d 選項。

您隨時可以使用 wslconfig.exe 手動切換預設發行版本。

例如

wslconfig /setdefault Ubuntu

您可以使用下列命令查看已安裝的發行版本

wslconfig /l

我看到關於遺失程式庫或依賴性的錯誤

某些擴充功能依賴於在某些 WSL Linux 發行版本的原始安裝中找不到的程式庫。您可以使用 Linux 發行版本的套件管理員將其他程式庫新增至 Linux 發行版本中。對於以 Ubuntu 和 Debian 為基礎的發行版本，請執行 sudo apt-get install <package> 以安裝所需的程式庫。查看擴充功能或提及的執行階段文件，以取得其他安裝詳細資訊。

WSL 擴充功能的連線需求為何？

WSL 擴充功能和 VS Code Server 需要對下列項目進行輸出 HTTPS (連接埠 443) 連線

  • update.code.visualstudio.com
  • marketplace.visualstudio.com
  • vscode.blob.core.windows.net
  • *.vo.msecnd.net (Azure CDN)
  • *.gallerycdn.vsassets.io (Azure CDN)

某些擴充功能 (例如 C#) 會從 download.microsoft.com 或 download.visualstudio.microsoft.com 下載次要依賴性。其他擴充功能 (例如 Visual Studio Live Share) 可能有其他連線需求。如果您遇到問題，請參閱擴充功能的文件以取得詳細資訊。

伺服器與 VS Code 用戶端之間的所有其他通訊都是透過隨機本機 TCP 連接埠完成的。您可以在網路連線文章中找到 VS Code 本身需要存取的位置清單。

我在 Proxy 後方，而且有連線問題

Windows 或 WSL 端可能遺失 Proxy 設定。

當從 VSCode 開啟遠端視窗時，WSL 擴充功能會嘗試在 Windows 端下載 VSCode 伺服器。因此，它會使用 Windows 端 Proxy 組態

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

一旦伺服器啟動並執行，就會使用 [遠端] 索引標籤上的 Proxy 設定。

我可以強制擴充功能在本機/遠端執行嗎？

擴充功能通常設計和測試為在本機或遠端執行，而不是兩者都執行。但是，如果擴充功能支援，您可以強制其在 settings.json 檔案中的特定位置執行。

例如，下列設定會強制 Docker 擴充功能在本機執行，並強制 Remote - SSH: Editing Configuration Files 擴充功能遠端執行，而不是其預設值

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

值 "ui" 而不是 "workspace" 將強制擴充功能在本機 UI/用戶端執行。通常，這應該只用於測試，除非擴充功能文件中另有說明，因為這可能會中斷擴充功能。如需詳細資訊，請參閱關於 支援遠端開發 的文章。

身為擴充功能作者，我需要做什麼？

VS Code 擴充功能 API 會抽象化本機/遠端詳細資訊，因此大多數擴充功能都可以正常運作，而無需修改。但是，由於擴充功能可以使用它們想要的任何節點模組或執行階段，因此在某些情況下可能需要進行調整。我們建議您測試您的擴充功能，以確保不需要更新。如需詳細資訊，請參閱 支援遠端開發。

問題或意見回饋

02/06/2025