探索 Agent 式開發 -

在 WSL 中進行開發

Visual Studio Code WSL 擴充功能讓您可以直接從 VS Code 將 Windows 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 Linux 子系統以及您偏好的 Linux 發行版。

    注意：WSL 1 對於某些類型的開發確實有一些已知限制。此外，由於擴充功能原生原始程式碼中的 glibc 相依性，安裝在 Alpine Linux 中的擴充功能可能無法運作。詳細資訊請參閱 遠端開發與 Linux 文章。

  2. 在 Windows 端（而非 WSL 內）安裝 Visual Studio Code。

    注意：在安裝過程中，當系統提示選取其他工作 (Select Additional Tasks) 時，請務必勾選 新增至 PATH (Add to PATH) 選項，以便您可以使用 code 命令輕鬆在 WSL 中開啟資料夾。

  3. 安裝 WSL 擴充功能。如果您計劃在 VS Code 中使用其他遠端擴充功能，您可以選擇安裝 遠端開發擴充功能套件 (Remote Development extension pack)。

開啟遠端資料夾或工作區

從 WSL 終端機

在 VS Code 中開啟 Windows 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+<發行版名稱> <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 內部。

如果您從「擴充功能」檢視中安裝擴充功能，它會自動安裝在正確的位置。安裝完成後，您可以根據類別分組判斷擴充功能安裝的位置。將會有一個 本機 - 已安裝 (Local - Installed) 類別，以及一個 WSL 的類別。

Workspace Extension Category

Local Extension Category

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

實際上需要遠端執行的本機擴充功能將會在 本機 - 已安裝 類別中顯示為灰色且已停用。選取 安裝 (Install) 即可在您的遠端主機上安裝擴充功能。

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（Insiders 版本為：~/.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 整合 (Settings > Resources > WSL Integration)，並啟用與您將要使用的 WSL 發行版的 Docker 整合。

  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），由 VS Code 啟動的檔案監視器所引起。此問題將僅在 WSL 2 中修復。

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

對於大型工作區，您可以增加輪詢間隔：remote.WSL.fileWatcher.pollingInterval，並控制要監視的資料夾： files.watcherExclude 在 VS Code 中開啟 在 VS Code Insiders 中開啟 。

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 透過 node 使用時，僅在 WSL 上極度緩慢 Microsoft/WSL#2657

Git 限制

如果您使用 SSH 複製 Git 儲存庫，且您的 SSH 金鑰有密碼（passphrase），VS Code 的提取與同步功能在遠端執行時可能會當機。解決方法是使用沒有密碼的 SSH 金鑰、透過 HTTPS 複製，或從命令列執行 git push。

Container Tools 擴充功能限制

雖然 Container Tools 擴充功能可以同時在遠端與本機執行，但如果它已經安裝在本機，您將無法在未先從本機解除安裝的情況下將其安裝在遠端 SSH 主機上。我們將在未來的 VS Code 版本中解決此問題。

擴充功能限制

許多擴充功能無需修改即可在 WSL 中運作。然而在某些情況下，特定功能可能需要變更。如果您遇到擴充功能問題，請參閱此處的常見問題與解決方案摘要，您可以在報告問題時提供給擴充功能作者參考。

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

常見問題

為什麼系統要求我變更預設發行版？

當使用 WSL: Connect to WSL using Distro 且在 Windows 10 2019 年 5 月更新 (1903 版) 之前的 WSL 版本上執行時，您將會被要求切換預設發行版，因為 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 本身需要存取的位置清單。

我位於 Proxy 後方，並有連線問題

Windows 或 WSL 端可能缺少 Proxy 設定。

當遠端視窗從 VS Code 開啟時，WSL 擴充功能會嘗試在 Windows 端下載 VS Code Server。因此，它會使用 Windows 端的 Proxy 設定

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

一旦伺服器啟動並執行後，將會使用「遠端 (Remote)」分頁上的 Proxy 設定。

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

擴充功能通常設計與測試為僅在本地或僅在遠端執行，而非兩者皆可。不過，如果擴充功能支援，您可以在 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 抽象化了本地/遠端的細節，因此大多數擴充功能無需修改即可運作。然而，由於擴充功能可以使用任何它們想要的 node 模組或執行環境，在某些情況下可能需要進行調整。我們建議您測試您的擴充功能，以確保無需更新。詳細資訊請參閱支援遠端開發。

問題或意見回饋

4/8/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.