在 WSL 中開發

Visual Studio Code WSL 擴充功能可讓您直接從 VS Code 使用適用於 Linux 的 Windows 子系統 (WSL) 作為您的全職開發環境。您可以在以 Linux 為基礎的環境中開發、使用 Linux 專用的工具鏈和公用程式，以及從舒適的 Windows 環境中執行和偵錯以 Linux 為基礎的應用程式。

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

這讓 VS Code 能夠提供本機品質的開發體驗，包括完整的 IntelliSense (完成)、程式碼導覽和偵錯，無論您的程式碼託管在哪裡。

開始使用

注意：檢閱本主題後，您可以開始使用簡介WSL 教學課程。

安裝

若要開始使用，您需要

1. 安裝適用於 Linux 的 Windows 子系統以及您偏好的 Linux 發行版本。

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

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

   注意：當安裝期間提示您選取其他工作時，請務必勾選 [新增至 PATH] 選項，以便您使用 code 命令輕鬆地在 WSL 中開啟資料夾。

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

開啟遠端資料夾或工作區

從 WSL 終端機

在 VS Code 中開啟適用於 Linux 的 Windows 子系統內的資料夾，與從命令提示字元或 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 中開啟資料夾。

   

   VS Code 現在將繼續在 WSL 中自行設定，並在進度更新時讓您隨時掌握最新資訊。

5. 完成後，您現在會在左下角看到 WSL 指示器，而且您將能夠像平常一樣使用 VS Code！

   

就是這樣！您在此視窗中執行的任何 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 類別。

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

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

您也可以將所有本機安裝的擴充功能安裝在 WSL 內部，方法是移至 [擴充功能] 檢視，然後使用 [本機 - 已安裝] 標題列右側的雲端按鈕，選取 [在 WSL 中安裝本機擴充功能: {名稱}]。這會顯示下拉式清單，您可以在其中選取要在 WSL 執行個體中安裝的本機安裝擴充功能。

在 WSL 中開啟終端機

從 VS Code 在 WSL 中開啟終端機很簡單。在 WSL 中開啟資料夾之後，您在 VS Code 中開啟的任何終端機視窗 ([終端機] > [新增終端機]) 都會在 WSL 中自動執行，而不是在本機執行。

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

在 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 整合]，然後啟用 Docker 與您將使用的 WSL 發行版本的整合。

2. 如果您尚未安裝，請連同 WSL 擴充功能一起安裝開發容器擴充功能。

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

4. 在 WSL 中開啟資料夾之後，從 [命令選擇區] (F1) 選取 [開發容器: 在容器中重新開啟]。

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

   

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

   

7. 建置完成後，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

WSL 1 中的 Node.js

Git 限制

如果您使用 SSH 複製 Git 存放庫，而且您的 SSH 金鑰有密碼，則 VS Code 的提取和同步功能在遠端執行時可能會停止回應。請使用沒有密碼的金鑰、使用 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 <套件> 以安裝所需的程式庫。查看擴充功能或提及的執行階段文件，以取得其他安裝詳細資訊。

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 設定

• 繼承自 OS 設定
• 如 Visual Studio Code 中的網路連線中所述

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

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

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

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

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

例如，下列設定會強制 Docker 擴充功能在本機執行，並強制 Remote - SSH: 編輯組態檔擴充功能在遠端執行，而不是使用其預設值

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

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

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

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

問題或意見反應

• 請參閱秘訣與訣竅或常見問題集。
• 在 Stack Overflow 上搜尋。
• 新增功能要求或回報問題。
• 貢獻我們的文件或 VS Code 本身。
• 如需詳細資訊，請參閱我們的CONTRIBUTING 指南。