在容器內進行開發

Visual Studio Code Dev Containers 擴充功能可讓您使用容器作為功能完整的開發環境。它允許您開啟容器內部（或掛載到容器中）的任何資料夾，並充分利用 Visual Studio Code 的完整功能集。專案中的 devcontainer.json 檔案會告訴 VS Code 如何存取（或建立）具有明確定義之工具與執行階段堆疊的開發容器。此容器可用於執行應用程式，或隔離處理程式碼基底所需的工具、程式庫或執行階段。

工作區檔案是從本機檔案系統掛載，或是複製到容器中。擴充功能會在容器內安裝並執行，它們可以完整存取工具、平台和檔案系統。這意味著您只需連線至不同的容器，就可以無縫切換整個開發環境。

Container Architecture

這讓 VS Code 能夠提供具備本機品質的開發體驗，包括完整的 IntelliSense（自動完成）、程式碼導覽和偵錯，無論您的工具（或程式碼）位於何處。

Dev Containers 擴充功能支援兩種主要的作業模型：

您可以將容器用作全職的開發環境
您可以附加至執行中的容器以進行檢查。

注意：Dev Containers 擴充功能支援開放的 Dev Containers 規格，讓任何人都能在任何工具中設定一致的開發環境。您可以在我們的 dev 容器常見問題集以及規格網站 containers.dev 上深入了解。

入門指南

Note: 您可以在入門的 Dev Containers 教學課程中，了解如何快速開始使用 dev 容器。

系統需求

本機 / 遠端主機

您可以用幾種方式將 Docker 與 Dev Containers 擴充功能搭配使用，包括：

安裝於本機的 Docker。
安裝在遠端環境中的 Docker。
其他相容於 Docker 的 CLI，可安裝於本機或遠端。
- 雖然其他 CLI 可能也可以運作，但官方並未支援。請注意，附加至 Kubernetes 叢集僅需要正確設定的 kubectl CLI。

您可以在替代 Docker 選項文件中深入了解。

以下是在本機或遠端主機上設定 Docker 的一些具體方式：

Windows：在 Windows 10 專業版/企業版上執行 Docker Desktop 2.0+。Windows 10 家用版 (2004+) 需要 Docker Desktop 2.3+ 以及 WSL 2 後端。（不支援 Docker Toolbox。不支援 Windows 容器映像檔。）
macOS：Docker Desktop 2.0+。
Linux：Docker CE/EE 18.06+ 與 Docker Compose 1.21+。（不支援 Ubuntu snap 套件。）
遠端主機：至少需要 1 GB RAM，但建議至少有 2 GB RAM 與 2 核心 CPU。

容器:

x86_64 / ARMv7l (AArch32) / ARMv8l (AArch64) Debian 9+、Ubuntu 16.04+、CentOS / RHEL 7+
x86_64 Alpine Linux 3.9+

如果其他基於 glibc 的 Linux 容器具備必要的 Linux 先決條件，也可能可以運作。

安裝

若要開始使用，請依照下列步驟操作：

為您的作業系統安裝並設定 Docker，可使用以下其中一種路徑或替代 Docker 選項（例如遠端主機上的 Docker 或相容於 Docker 的 CLI）。

Windows / macOS:
1. 安裝 Docker Desktop for Windows/Mac。
2. 如果您在 Windows 上使用 WSL 2，為確保已啟用 WSL 2 後端：在工作列的 Docker 項目上按一下滑鼠右鍵，然後選取設定 (Settings)。勾選使用以 WSL 2 為基礎的引擎 (Use the WSL 2 based engine)，並確認您的發行版本已在資源 (Resources) > WSL 整合 (WSL Integration) 下啟用。
3. 當未使用 WSL 2 後端時，請在工作列的 Docker 項目上按一下滑鼠右鍵，選取設定 (Settings)，並在資源 (Resources) > 檔案共用 (File Sharing) 中更新存放原始程式碼的任何位置。如需疑難排解，請參閱提示與技巧。
Linux:
1. 請依照適用於您發行版本的 Docker CE/EE 官方安裝說明操作。如果您使用 Docker Compose，也請遵循 Docker Compose 指南。
2. 使用終端機執行下列命令，將您的使用者新增至 docker 群組：sudo usermod -aG docker $USER
3. 登出然後重新登入，以使變更生效。
安裝 Visual Studio Code 或 Visual Studio Code Insiders。
安裝 Dev Containers 擴充功能。如果您打算在 VS Code 中使用其他遠端擴充功能，您可以選擇安裝 Remote Development 擴充功能套件。

正在使用 Git？

以下提供兩點建議：

如果您同時在 Windows 本機和容器內使用相同的儲存庫，請務必設定一致的行結尾。詳細資訊請參閱提示與技巧。
如果您使用 Git 憑證管理員進行複製，您的容器應該已經可以存取您的憑證！如果您使用 SSH 金鑰，也可以選擇共用它們。詳細資訊請參閱與容器共用 Git 憑證。

選擇您的快速入門

本文件包含 3 種快速入門方式 - 我們建議從最符合您的工作流程和興趣的一種開始：

想在快速範例儲存庫中試用 dev 容器嗎？請參閱快速入門 1：嘗試開發容器。
想將 dev 容器新增至現有的本機複製專案中嗎？請參閱快速入門 2：在容器中開啟現有資料夾。
想使用儲存庫的隔離複本（例如審查 PR 或調查分支而不影響本機工作）嗎？請參閱快速入門 3：在隔離的容器磁碟區中開啟 Git 儲存庫或 PR。

快速入門：嘗試開發容器

開始使用的最簡單方法是嘗試其中一個範例開發容器。容器教學課程將引導您設定 Docker 和 Dev Containers 擴充功能，並讓您選取一個範例。

Select a sample from the list

注意：如果您已經安裝 VS Code 和 Docker，則可以使用在 dev 容器中開啟。您可以在建立 dev 容器指南中深入了解此功能以及如何將其新增至您的儲存庫。

快速入門：在容器中開啟現有資料夾

本快速入門涵蓋如何使用檔案系統上的現有原始程式碼，為現有專案設定 dev 容器以作為全職開發環境。請依照下列步驟操作：

啟動 VS Code，從命令選擇區（F1）或快速動作狀態列項目執行 Dev Containers: Open Folder in Container... 命令，然後選取您要為其設定容器的專案資料夾。

提示：如果您想在開啟資料夾之前編輯容器的內容或設定，可以改為執行 Dev Containers: Add Dev Container Configuration Files...。
現在為您的 dev 容器選擇一個起點。您可以從可篩選的清單中選取基本的開發容器範本 (Dev Container Template)，或者如果您選取的資料夾中已有 Dockerfile 或 Docker Compose 檔案，則可使用現有的檔案。

注意：使用 Alpine Linux 容器時，某些擴充功能可能因擴充功能內的原生程式碼依賴 glibc 而無法運作。

清單將會根據您開啟的資料夾內容自動排序。

您可能可以使用額外功能來自訂您的 dev 容器，您可以在下方閱讀更多相關資訊。

顯示的 dev 容器範本來自我們的官方與社群索引，這是 Dev Container Specification 的一部分。我們在 devcontainers/templates 儲存庫中作為規格的一部分託管了一組範本。您可以瀏覽該儲存庫的 src 資料夾以查看每個範本的內容。

您也可以選擇使用 dev container CLI 發布和散布您自己的 dev 容器範本。
選擇容器的起點後，VS Code 會將 dev 容器設定檔新增至您的專案（.devcontainer/devcontainer.json）。
VS Code 視窗將會重新載入並開始建置 dev 容器。進度通知會提供狀態更新。您只需在第一次開啟 dev 容器時建置它；首次成功建置後再次開啟資料夾會快得多。
建置完成後，VS Code 會自動連線至容器。

您現在可以在 VS Code 中與您的專案互動，就像在本機開啟專案一樣。從現在開始，當您開啟專案資料夾時，VS Code 將會自動偵測並重複使用您的 dev 容器設定。

提示：想要使用遠端 Docker 主機嗎？如需相關資訊，請參閱在容器中開啟遠端 SSH 主機上的資料夾一節。

雖然使用這種方法將本機檔案系統繫結掛載到容器中很方便，但它在 Windows 和 macOS 上確實有一些效能負擔。您可以套用一些技巧來改善磁碟效能，或者改為使用隔離的容器磁碟區在容器中開啟儲存庫。

在 Windows 上的容器中開啟 WSL 2 資料夾

如果您使用 Windows Subsystem for Linux v2 (WSL 2) 並已啟用 Docker Desktop 的 WSL 2 後端，您就可以處理儲存在 WSL 內的原始程式碼！

啟用 WSL 2 引擎後，您可以選擇：

從已使用 WSL 擴充功能開啟的資料夾中執行 Dev Containers: Reopen in Container 命令。
從命令選擇區（F1）選取 Dev Containers: Open Folder in Container...，並使用本機 \\wsl$ 共用（從 Windows 端）選擇 WSL 資料夾。

其餘的快速入門步驟完全適用！您可以在 WSL 擴充功能說明文件中深入了解。

在容器中開啟遠端 SSH 主機上的資料夾

如果您使用 Linux 或 macOS SSH 主機，可以將 Remote - SSH 與 Dev Containers 擴充功能搭配使用。您甚至不需要在本機安裝 Docker 用戶端。

執行方式如下：

請依照 Remote - SSH 擴充功能的安裝和 SSH 主機設定步驟操作。
選用：設定 SSH 基於金鑰的驗證，這樣您就不需要多次輸入密碼。
在您的 SSH 主機上安裝 Docker。您不需要在本機安裝 Docker。
請依照 Remote - SSH 擴充功能的快速入門連線至主機並在該處開啟資料夾。
使用命令面板中的 Dev Containers: Reopen in Container 指令（F1 或 ⇧⌘P）。

其餘的 Dev Containers 快速入門步驟完全適用。您可以在 Remote - SSH 擴充功能說明文件中深入了解。如果此模型不符合您的需求，您也可以參閱在遠端 Docker 主機上開發一文以了解其他選項。

在容器中開啟遠端通道主機上的資料夾

您可以將 Remote - Tunnels 與 Dev Containers 擴充功能搭配使用，以在容器內開啟遠端主機上的資料夾。您甚至不需要在本機安裝 Docker 用戶端。這與上面的 SSH 主機情境類似，但改為使用 Remote - Tunnels。

執行方式如下：

請依照 Remote - Tunnels 擴充功能的開始使用說明操作。
在您的通道主機上安裝 Docker。您不需要在本機安裝 Docker。
請依照 Remote - Tunnels 擴充功能的步驟連線至通道主機並在該處開啟資料夾。
使用命令面板中的 Dev Containers: Reopen in Container 指令（F1 或 ⇧⌘P）。

其餘的 Dev Containers 快速入門步驟完全適用。您可以在 Remote - Tunnels 擴充功能說明文件中深入了解。如果此模型不符合您的需求，您也可以參閱在遠端 Docker 主機上開發一文以了解其他選項。

在容器中開啟現有的工作區

如果工作區僅參考 .code-workspace 檔案所在資料夾的子資料夾（或資料夾本身）的相對路徑，您也可以遵循類似的程序在單一容器中開啟 VS Code 多根目錄工作區。

您可以選擇：

使用 Dev Containers: Open Workspace in Container... 命令。
一旦您在容器中開啟包含 .code-workspace 檔案的資料夾後，請使用檔案 > 開啟工作區...。

連線後，如果您還看不到 .devcontainer 資料夾，您可能會想要將其新增至工作區，以便輕鬆編輯其內容。

另請注意，雖然您無法在同一個 VS Code 視窗中為相同工作區使用多個容器，但您可以從不同的視窗同時使用多個由 Docker Compose 管理的容器。

快速入門：在隔離的容器磁碟區中開啟 Git 儲存庫或 GitHub PR

雖然您可以在容器中開啟本機複製的儲存庫，但您可能會希望使用儲存庫的隔離複本來進行 PR 審查或調查其他分支，而不影響您的工作。

儲存庫容器使用隔離的本機 Docker 磁碟區，而不是繫結至本機檔案系統。除了不會污染您的檔案樹之外，本機磁碟區還有改善 Windows 和 macOS 效能的額外好處。（如需如何在其他情境中使用這些類型磁碟區的資訊，請參閱進階設定改善磁碟效能一文。）

例如，請依照下列步驟在儲存庫容器中開啟其中一個「try」儲存庫：

啟動 VS Code，並從命令選擇區（F1）執行 Dev Containers: Clone Repository in Container Volume...。
在出現的輸入方塊中輸入 microsoft/vscode-remote-try-node（或其他「try」儲存庫之一）、Git URI、GitHub 分支 URL 或 GitHub PR URL，然後按下 Enter。

提示：如果您選擇私人儲存庫，您可能會想要設定憑證管理員或將您的 SSH 金鑰新增至 SSH 代理程式。請參閱與您的容器共用 Git 憑證。
如果您的儲存庫中沒有 .devcontainer/devcontainer.json 檔案，系統會要求您從可篩選的清單或現有的 Dockerfile 或 Docker Compose 檔案（若存在）中選擇起點。

注意：使用 Alpine Linux 容器時，某些擴充功能可能因擴充功能內的原生程式碼依賴 glibc 而無法運作。

清單將會根據您開啟的資料夾內容自動排序。顯示的 dev 容器範本來自我們的官方與社群索引，這是 Dev Container Specification 的一部分。我們在 devcontainers/templates 儲存庫中作為規格的一部分託管了一組範本。您可以瀏覽該儲存庫的 src 資料夾以查看每個範本的內容。
VS Code 視窗（執行個體）將會重新載入、複製原始程式碼，並開始建置 dev 容器。進度通知會提供狀態更新。

如果您在步驟 2 中貼上了 GitHub 提取要求 URL，該 PR 將會自動被切換簽出，並且 GitHub Pull Requests 擴充功能將會安裝在容器中。此擴充功能提供其他與 PR 相關的功能，例如 PR 總管、在行內與 PR 註解互動，以及狀態列可見性。
建置完成後，VS Code 將會自動連線至容器。您現在可以在此獨立環境中處理儲存庫原始程式碼，就像在本機複製程式碼一樣。

請注意，如果容器因 Docker 建置錯誤等原因而無法啟動，您可以在出現的對話方塊中選取在修復容器中重新開啟，以進入「修復容器」，這允許您編輯 Dockerfile 或其他內容。這會在最小化的容器中開啟包含已複製儲存庫的 docker 磁碟區，並向您顯示建立記錄。修復完成後，請使用在容器中重新開啟來重試。

提示：想要使用遠端 Docker 主機嗎？如需相關資訊，請參閱在容器中開啟遠端 SSH 主機上的資料夾一節。

信任您的工作區

Visual Studio Code 非常重視安全性，並希望無論來源或原始作者為何，都能協助您安全地瀏覽和編輯程式碼。工作區信任功能可讓您決定專案資料夾是否應該允許或限制自動程式碼執行。

Dev Containers 擴充功能已採用工作區信任。根據您開啟和與原始程式碼互動的方式，系統會在不同時間點提示您決定是否信任您正在編輯或執行的程式碼。

在容器中重新開啟資料夾

為現有專案設定 dev 容器需要信任本機（或 WSL）資料夾。在視窗重新載入之前，系統會要求您信任本機（或 WSL）資料夾。

此流程有一些例外狀況：

當按一下近期項目時。
如果尚未授予信任，使用 Open Folder in Container 命令將會在視窗重新載入後詢問信任。

附加至現有容器

當附加至現有容器時，系統會要求您確認附加即表示您信任該容器。這只需要確認一次。

Workspace trust prompt when attaching to container

在磁碟區中複製儲存庫

當在容器磁碟區中複製儲存庫時，系統會要求您確認複製儲存庫即表示您信任該儲存庫。這只需要確認一次。

Workspace trust prompt when cloning in container volume

檢查磁碟區

檢查磁碟區會以受限制模式啟動，您可以信任容器內的資料夾。

Docker daemon 正在遠端執行

這意味著信任執行 Docker daemon 的機器。沒有其他確認提示（僅有上述本機/WSL 情況所列的提示）。

建立 devcontainer.json 檔案

VS Code 的容器設定儲存在 devcontainer.json 檔案中。此檔案類似於用於偵錯設定的 launch.json 檔案，但改為用於啟動（或附加至）您的開發容器。您也可以指定容器執行後要安裝的任何擴充功能，或用來準備環境的建立後執行命令。dev 容器設定位於 .devcontainer/devcontainer.json 下，或者作為專案根目錄中的 .devcontainer.json 檔案儲存（請注意點前綴）。

從命令選擇區（F1）選取 Dev Containers: Add Dev Container Configuration Files... 命令，會將所需的檔案新增至您的專案作為起點，您可以根據需求進一步自訂這些檔案。此命令可讓您根據資料夾內容從清單中挑選預先定義的容器設定、重複使用現有的 Dockerfile，或重複使用現有的 Docker Compose 檔案。

Select a node Dev Container Template

您也可以手動建立 devcontainer.json，並使用任何映像檔、Dockerfile 或一組 Docker Compose 檔案作為起點。以下是一個簡單的範例，它使用了其中一個預先建置的開發容器映像檔：

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",
  "forwardPorts": [3000],
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      // Add the IDs of extensions you want installed when the container is created.
      "extensions": ["streetsidesoftware.code-spell-checker"]
    }
  }
}

注意：系統會根據基礎映像檔中的內容，自動將額外的設定新增至容器中。例如，我們在上方新增了 streetsidesoftware.code-spell-checker 擴充功能，且容器也會包含 "dbaeumer.vscode-eslint"，因為這是 mcr.microsoft.com/devcontainers/typescript-node 的一部分。當使用 devcontainer.json 進行預先建置時，這會自動發生，您可以在預先建置章節中閱讀更多相關資訊。

若要深入了解如何建立 devcontainer.json 檔案，請參閱建立開發容器。

開發容器功能

開發容器「功能」是獨立的、可共用的安裝程式碼與 dev 容器設定單元。這個名稱的概念是，參考其中一個功能可讓您快速且輕鬆地將更多工具、執行階段或程式庫「功能」新增至您的開發容器中，供您或您的協作者使用。

當您使用 Dev Containers: Add Dev Container Configuration Files 時，系統會向您顯示一系列指令碼以自訂現有的 dev 容器設定，例如安裝 Git 或 Azure CLI：

Dev container Features list drop down

當您在容器中重建並重新開啟時，您所選的功能將會在您的 devcontainer.json 中可用。

"features": {
    "ghcr.io/devcontainers/features/github-cli:1": {
        "version": "latest"
    }
}

當直接在 devcontainer.json 中編輯 "features" 屬性時，您將獲得 IntelliSense。

Intellisense when modifying terraform Feature

Dev Containers: Configure Container Features 命令允許您更新現有的設定。

VS Code UI 中來源的功能現在來自中央索引，您也可以為其貢獻。如需目前的清單以及了解如何發布和散布功能，請參閱 Dev Containers 規格網站。

「永遠安裝」功能

就像您可以設定擴充功能在 dev 容器中永遠安裝一樣，您可以使用 dev.containers.defaultFeatures 在 VS Code 中開啟在 VS Code Insiders 中開啟使用者設定來設定您希望永遠安裝的功能

"dev.containers.defaultFeatures": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
},

建立您自己的功能

建立和發布您自己的 Dev Container 功能也很容易。發布的功能可以作為 OCI Artifacts 從任何支援的公開或私人容器登錄檔儲存和共用。您可以在 containers.dev 上查看目前發布的功能清單。

功能是資料夾中的獨立實體，至少包含一個 devcontainer-feature.json 和 install.sh 入口點指令碼

+-- feature
|    +-- devcontainer-feature.json
|    +-- install.sh
|    +-- (other files)

請參閱 feature/starter 儲存庫，以取得使用 dev container CLI 發布您自己的公開或私人功能的說明。

功能規格與散布

功能是開源 Development Containers Specification 的關鍵部分。您可以檢閱關於功能如何運作的更多資訊及其散布方式。

預先建置開發容器映像檔

我們建議使用您需要的工具預先建置映像檔，而不是每次在 dev 容器中開啟專案時都建立並建置容器映像檔。使用預先建置的映像檔將會加快容器啟動速度、簡化設定，並允許您鎖定特定版本的工具以改善供應鏈安全並避免潛在的中斷。您可以透過使用 GitHub Actions 等 DevOps 或持續整合 (CI) 服務排程建置，來自動化預先建置您的映像檔。

更棒的是，預先建置的映像檔可以包含 Dev Container 中繼資料，因此當您參考映像檔時，設定將會自動被拉取過來。

我們建議使用 Dev Container CLI（或其他支援規格的公用程式，例如 GitHub Action）來預先建置您的映像檔，因為它與 Dev Containers 擴充功能的最新功能保持同步，包括開發容器功能。一旦您建置了映像檔，就可以將它推送至容器登錄檔（例如 Azure Container Registry、GitHub Container Registry 或 Docker Hub）並直接參考它。

您可以使用 devcontainers/ci 儲存庫中的 GitHub Action 來協助您在工作流程中重複使用 dev 容器。

如需詳細資訊，請前往關於預先建置映像檔的 dev container CLI 文章。

繼承中繼資料

您可以透過映像檔標籤在預先建置的映像檔中包含 Dev Container 設定與功能中繼資料。這使映像檔具備自包含性，因為當參考映像檔時（無論是直接參考、在所參考 Dockerfile 中的 FROM，還是在 Docker Compose 檔案中），這些設定都會自動被擷取。這有助於防止您的 Dev Container 設定與映像檔內容不同步，並允許您透過簡單的映像檔參考將相同設定的更新推送至多個儲存庫。

當您使用 Dev Container CLI（或其他支援規格的公用程式，例如 GitHub Action 或 Azure DevOps 工作）進行預先建置時，此中繼資料標籤會自動新增，並且包含來自 devcontainer.json 以及任何參考的 Dev Container 功能的設定。

這可讓您擁有一個用於預先建置映像檔的獨立、較複雜的 devcontainer.json，然後在一個或多個儲存庫中使用大幅簡化的版本。當您建立容器時，映像檔的內容將與這個簡化的 devcontainer.json 內容進行合併（有關合併邏輯的資訊，請參閱規格）。但在最簡單的情況下，您只需在 devcontainer.json 中直接參考該映像檔即可讓設定生效：

{
  "image": "mcr.microsoft.com/devcontainers/go:1"
}

請注意，您也可以選擇改為手動將中繼資料新增至映像檔標籤。即使您未使用 Dev Container CLI 進行建置，這些屬性也會被擷取（如果您使用了，也可以由 CLI 進行更新）。例如，考慮以下 Dockerfile 程式碼片段：

LABEL devcontainer.metadata='[{ \
  "capAdd": [ "SYS_PTRACE" ], \
  "remoteUser": "devcontainer", \
  "postCreateCommand": "yarn install" \
}]'

檢查磁碟區

有時候您可能會遇到這樣的情況：您正在使用一個具名的 Docker 磁碟區，並想要檢查它或在其中進行變更。您可以透過從命令選擇區（F1）選取 Dev Containers: Explore a Volume in a Dev Container...，來使用 VS Code 處理這些內容，而無需建立或修改 devcontainer.json 檔案。

您也可以在遠端總管中檢查您的磁碟區。請確定您在下拉式選單中選取了「容器」，接著您會注意到一個 Dev Volumes 區段。您可以在磁碟區上按一下滑鼠右鍵以檢查其建立資訊，例如建立磁碟區的時間、複製到其中的儲存庫以及掛載點。您也可以在 dev 容器中瀏覽它。

Right-click dev volumes in Remote Explorer

如果您已安裝 Container Tools 擴充功能，您可以在 Container Explorer 的 Volumes 區段中的磁碟區上按一下滑鼠右鍵，然後選取 Explore in a Development Container。

Explore in dev container in Container Tools context menu

管理擴充功能

VS Code 在兩個地方之一執行擴充功能：本機的 UI / 用戶端側，或是在容器中。雖然會影響 VS Code UI 的擴充功能（例如佈景主題與程式碼片段）是安裝在本機上，但大多數擴充功能都會駐留在特定的容器內。這可讓您僅在容器中安裝特定任務所需的擴充功能，並僅透過連線至新的容器即可無縫切換整個工具鏈。

如果您從「擴充功能」檢視安裝擴充功能，它將會自動安裝在正確的位置。您可以根據類別群組來判斷擴充功能的安裝位置。將會有一個 Local - Installed 類別，以及另一個對應您容器的類別。

Workspace Extension Category

Local Extension Category

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

實際上需要在遠端執行的本機擴充功能，在 Local - Installed 類別中會顯示為已停用。選取安裝即可在您的遠端主機上安裝擴充功能。

Disabled Extensions w/Install Button

您也可以前往「擴充功能」檢視，並使用 Local - Installed 標題列右側的雲端按鈕選取 Install Local Extensions in Dev Container: {Name}，以在 Dev Container 內安裝所有本機安裝的擴充功能。這將會顯示一個下拉式選單，您可以在其中選取要在容器中安裝哪些本機安裝的擴充功能。

Install all extensions

不過，某些擴充功能可能會要求您在容器中安裝額外的軟體。如果遇到問題，請參閱擴充功能說明文件以了解詳細資訊。

將擴充功能新增至 devcontainer.json

雖然您可以手動編輯 devcontainer.json 檔案以新增擴充功能 ID 清單，但您也可以在「擴充功能」檢視中的任何擴充功能上按一下滑鼠右鍵，然後選取 Add to devcontainer.json。

Add to devcontainer.json menu

退出擴充功能

如果基礎映像檔或功能設定了您不想安裝在 dev 容器中的擴充功能，您可以透過在擴充功能前加上減號來退出。例如：

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
  "customizations": {
    "vscode": {
      "extensions": ["-dbaeumer.vscode-eslint"]
    }
  }
}

「永遠安裝」擴充功能

如果有些擴充功能希望在任何容器中都永遠安裝，您可以更新 dev.containers.defaultExtensions 在 VS Code 中開啟在 VS Code Insiders 中開啟使用者設定。例如，如果您想要安裝 GitLens 與 Resource Monitor 擴充功能，您可以指定其擴充功能 ID，如下所示：

"dev.containers.defaultExtensions": [
    "eamodio.gitlens",
    "mutantdino.resourcemonitor"
]

進階：強制擴充功能在本機或遠端執行

擴充功能通常設計與測試為僅在本地或僅在遠端執行，而非兩者皆可。不過，如果擴充功能支援，您可以在 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/用戶端側執行。通常這應該僅用於測試，除非擴充功能的文件中另有說明，因為它可能會破壞擴充功能。詳細資訊請參閱關於偏好的擴充功能位置一節。

轉發或發布連接埠

容器是獨立的環境，因此如果您想要存取容器內的伺服器、服務或其他資源，您需要將連接埠「轉發」或「發布」至您的主機。您可以將容器設定為永遠公開這些連接埠，或是僅暫時轉發它們。

永遠轉發連接埠

您可以使用 devcontainer.json 中的 forwardPorts 屬性，指定當附加或在容器中開啟資料夾時，您永遠想要轉發的連接埠清單。

"forwardPorts": [3000, 3001]

只需重新載入 / 重新開啟視窗，當 VS Code 連線至容器時，就會套用此設定。

暫時轉發連接埠

如果您需要存取未新增至 devcontainer.json 或未在 Docker Compose 檔案中發布的連接埠，您可以透過從命令選擇區（F1）執行 Forward a Port 命令，在工作階段期間暫時轉發新的連接埠。

Forward port input

選取連接埠後，通知會告訴您應用於存取容器中連接埠的 localhost 連接埠。例如，如果您轉發了接聽連接埠 3000 的 HTTP 伺服器，通知可能會告訴您它已被對應至 localhost 上的連接埠 4123。然後，您可以使用 https://:4123 連線至此遠端 HTTP 伺服器。

如果您稍後需要存取它，可以在遠端總管的 Forwarded Ports 區段中找到相同的資訊。

如果您希望 VS Code 記住您已轉發的任何連接埠，請在設定編輯器（⌘, (Windows, Linux Ctrl+,)）中勾選 Remote: Restore Forwarded Ports，或在 settings.json 中設定 "remote.restoreForwardedPorts": true。

Restore forwarded ports setting

發布連接埠

Docker 在建立容器時具有「發布」連接埠的概念。發布的連接埠運作方式非常類似於您提供給本機網路使用的連接埠。如果您的應用程式只接受來自 localhost 的呼叫，它將會拒絕來自發布連接埠的連線，就像您的本機對網路呼叫所做的一樣。另一方面，轉發的連接埠對應用程式來說實際上看起來像 localhost。兩者在不同的情境下都很有用。

若要發布連接埠，您可以：

使用 appPort 屬性：如果您在 devcontainer.json 中參考映像檔或 Dockerfile，您可以使用 appPort 屬性將連接埠發布至主機。
```
"appPort": [ 3000, "8921:5000" ]
```
使用 Docker Compose 連接埠對應：可以輕鬆地將連接埠對應新增至您的 docker-compose.yml 檔案以發布額外的連接埠。
```
ports:
- "3000"
- "8921:5000"
```

在每種情況下，您都需要重建容器才能讓設定生效。當您連線至容器時，可以在命令選擇區（F1）中執行 Dev Containers: Rebuild Container 命令來做到這點。

開啟終端機

從 VS Code 在容器中開啟終端機非常簡單。一旦您在容器中開啟資料夾，您在 VS Code 中開啟的任何終端機視窗（終端機 > 新增終端機）都會自動在容器中執行，而不是在本機執行。

您也可以從此相同的終端機視窗使用 code 命令列來執行許多操作，例如在容器中開啟新檔案或資料夾。輸入 code --help 以了解命令列提供哪些選項。

Using the code CLI

在容器中進行偵錯

一旦您在容器中開啟資料夾，您就可以使用與在本機執行應用程式時相同的方式來使用 VS Code 的偵錯工具。例如，如果您在 launch.json 中選取啟動設定並開始偵錯（F5），應用程式將會在遠端主機上啟動並將偵錯工具附加至它。

關於在 .vscode/launch.json 中設定 VS Code 偵錯功能的詳細資訊，請參閱偵錯文件。

容器特定設定

當您連線至 dev 容器時，也會重複使用 VS Code 的本機使用者設定。雖然這可保持您的使用者體驗一致，但您可能會希望在本機與每個容器之間變更其中某些設定。幸運的是，一旦您連線至容器，您也可以透過從命令選擇區（F1）執行 Preferences: Open Remote Settings 命令，或透過在設定編輯器中選取 Remote 索引標籤來設定容器特定設定。每當您連線至容器時，這些設定將會覆寫您現有的任何本機設定。

Container specific settings tab

預設的容器特定設定

您可以使用 settings 屬性在 devcontainer.json 中包含容器特定設定的預設值。建立容器後，這些值將會自動放置在容器內的容器特定設定檔案中。

例如，將此內容新增至 .devcontainer/devcontainer.json 將會設定 Java 家目錄路徑：

// Configure tool-specific properties.
"customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
        "settings": {
            "java.home": "/docker-java-home"
        }
    }
}

由於這只是建立預設值，因此在建立容器後，您仍然可以根據需要變更設定。

管理容器

根據預設，當您開啟資料夾時，Dev Containers 擴充功能會自動啟動 devcontainer.json 中提及的容器。當您關閉 VS Code 時，擴充功能會自動關閉您已連線的容器。您可以在 devcontainer.json 中新增 "shutdownAction": "none" 來變更此行為。

雖然您可以使用命令線上管理容器，但您也可以使用遠端總管。若要停止容器，請從下拉式選單中選取「容器」（若存在），在執行中的容器上按一下滑鼠右鍵，然後選取 Stop Container。您也可以啟動已結束的容器、移除容器以及移除近期資料夾。從「詳細資料」檢視中，您可以轉發連接埠並在瀏覽器中開啟已轉發的連接埠。

Containers Explorer screenshot

如果您想清除映像檔或大量刪除容器，請參閱清除未使用的容器與映像檔以了解不同的選項。

使用 dotfiles 儲存庫進行個人化

Dotfiles 是檔名以點 (.) 開頭的檔案，通常包含各種應用程式的設定資訊。由於開發容器可以涵蓋廣泛的應用程式類型，因此將這些檔案儲存在某處會很有用，以便在容器啟動並執行後，您可以輕鬆地將它們複製到容器中。

常見的做法是將這些 dotfiles 儲存在 GitHub 儲存庫中，然後使用公用程式來複製並套用它們。Dev Containers 擴充功能內建支援將這些檔案用於您自己的容器。如果您對這個概念不熟悉，請查看現有的各種 dotfiles 引導儲存庫。

若要使用它，請將您的 dotfiles GitHub 儲存庫新增至 VS Code 的使用者設定（⌘, (Windows, Linux Ctrl+,)），如下所示：

Settings for dotfiles

或者在 settings.json 中：

{
  "dotfiles.repository": "your-github-id/your-dotfiles-repo",
  "dotfiles.targetPath": "~/dotfiles",
  "dotfiles.installCommand": "install.sh"
}

從此開始，只要建立容器，就會使用 dotfiles 儲存庫。

已知限制

Dev Containers 限制

不支援 Windows 容器映像檔。
多根目錄工作區中的所有根目錄/資料夾都將在同一個容器中開啟，無論較低層級是否有設定檔。
不支援適用於 Linux 的非官方 Ubuntu Docker snap 套件。請遵循適用於您發行版本的 Docker 官方安裝說明。
不支援 Windows 上的 Docker Toolbox。
如果您使用 SSH 複製 Git 儲存庫，且您的 SSH 金鑰有密碼（passphrase），VS Code 的提取與同步功能在遠端執行時可能會當機。解決方法是使用沒有密碼的 SSH 金鑰、透過 HTTPS 複製，或從命令列執行 git push。
本機代理伺服器設定不會在容器內重複使用，這可能會阻止擴充功能運作，除非設定了適當的代理伺服器資訊（例如具有適當代理伺服器資訊的全域 HTTP_PROXY 或 HTTPS_PROXY 環境變數）。
當 Windows 上的 ssh-agent 執行版本 <= 8.8 且 SSH 用戶端（在任何平台上）執行版本 >= 8.9 時，Windows 上的 OpenSSH 版本之間存在不相容性。因應措施是將 Windows 上的 OpenSSH 升級至 8.9 或更新版本，可透過 winget 或來自 Win32-OpenSSH/releases 的安裝程式來升級。（請注意，ssh-add -l 將正常運作，但 ssh <ssh-server> 將會失敗並顯示 <ssh-server>: Permission denied (publickey)。當使用 SSH 連線至儲存庫時，這也會影響 Git。）

請參閱此處以取得與容器相關的有效問題清單。

Docker 限制

如需詳細資訊，請參閱適用於 Windows 或 Mac 的 Docker 疑難排解指南。

Container Tools 擴充功能限制

如果您從 WSL、Remote - Tunnels 或 Remote - SSH 視窗使用 Container Tools 或 Kubernetes 擴充功能，使用 Container Explorer 或 Kubernetes 檢視中的 Attach Visual Studio Code 滑鼠右鍵功能表動作，將會要求再次從可用的容器中進行選擇。

擴充功能限制

此時，大多數擴充功能無需修改即可在 Dev Containers 內運作。但是，在某些情況下，某些功能可能需要變更。如果您遇到擴充功能問題，請參閱此處以取得常見問題與解決方案的總結，您可以在回報問題時向擴充功能作者提及這些內容。

此外，雖然提供 Alpine 支援，但由於擴充功能內部原生程式碼中的 glibc 相依性，安裝在容器中的某些擴充功能可能無法運作。詳細資訊請參閱使用 Linux 進行遠端開發一文。

進階容器設定

如需下列主題的資訊，請參閱進階容器設定文章：

devcontainer.json 參考

有一份完整的 devcontainer.json 參考，您可以在其中檢閱檔案結構描述，以協助您自訂開發容器並控制如何附加至執行中的容器。

問題或意見回饋

請參閱提示與技巧或常見問題集。
在 Stack Overflow 上搜尋。
提出功能需求或回報問題。
建立一個開發容器範本或功能供他人使用。
檢閱 Development Containers Specification 並提供意見反應。
為我們的文件或 VS Code 本身做出貢獻。
詳細資訊請參閱我們的 CONTRIBUTING 指南。

疑難排解

無法寫入檔案 (NoPermissions (FileSystemError))

當您在以下設定中執行 dev 容器時，可能會遇到此問題：

Docker Desktop 使用 Windows Subsystem for Linux (WSL) 後端執行
已啟用增強型容器隔離 (ECI)

請查看 issue #8278 以取得可能的因應措施。

後續步驟

附加至執行中的容器 - 附加至已經在執行的 Docker 容器。
建立開發容器 - 為您的工作環境建立自訂容器。
進階容器 - 尋找進階容器場景的解決方案。
devcontainer.json 參考 - 查看 devcontainer.json 架構。

7/29/2026