建立開發容器

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code Dev Containers 擴充套件允許您使用 Docker 容器作為功能齊全的開發環境。它允許您在容器中開啟任何資料夾或倉庫，並利用 Visual Studio Code 的全部功能。專案中的 devcontainer.json 檔案會告訴 VS Code 如何訪問（或建立）一個具有定義明確的工具和執行時堆疊的開發容器。此容器可用於執行應用程式或提供與程式碼庫配合工作所需的獨立工具、庫或執行時。

建立開發容器的路徑

本文件將介紹在 VS Code 中建立開發（dev）容器的步驟

建立一個 devcontainer.json 檔案，該檔案描述了 VS Code 應如何啟動容器以及連線後執行的操作。
透過使用 Dockerfile 來製作和持久化對開發容器的更改，例如安裝新軟體。
透過 Docker Compose 配置多個容器。
在進行更改時，請構建您的開發容器以確保更改生效。

完成以上任何一個步驟後，您將擁有一個功能齊全的開發容器，您可以繼續本教程的下一步來新增更多功能，或者停止並開始使用您當前的開發環境。

注意：Dev Containers 擴充套件有一個Dev Containers: Add Dev Container Configuration Files...命令，可讓您從列表中選擇預定義的容器配置。如果您希望立即獲得完整的開發容器而不是一步一步地構建 devcontainer.json 和 Dockerfile，可以跳至自動化開發容器建立。

建立 devcontainer.json 檔案

VS Code 的容器配置儲存在 devcontainer.json 檔案中。此檔案類似於用於除錯配置的 launch.json 檔案，但用於啟動（或附加到）您的開發容器。開發容器配置要麼位於 .devcontainer/devcontainer.json 下，要麼儲存在專案根目錄下的 .devcontainer.json 檔案（注意點字首）中。

您可以使用映象作為 devcontainer.json 的起點。映象就像一個帶有各種預裝工具和作業系統的微型磁碟驅動器。您可以從容器登錄檔中拉取映象，容器登錄檔是儲存映象的倉庫集合。以下是一個使用預構建的 TypeScript 和 Node.js VS Code 開發容器映象的簡單示例 devcontainer.json

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18"
}

您可以修改配置以執行諸如以下操作

在容器中安裝 Git 等其他工具。
自動安裝擴充套件。
轉發或釋出其他埠。
設定執行時引數。
重用或擴充套件現有的 Docker Compose 設定。
新增更多高階容器配置。

在本示例中，如果您想在容器中安裝Code Spell Checker 擴充套件並自動轉發埠 3000，您的 devcontainer.json 將如下所示

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",

  "customizations": {
    "vscode": {
      "extensions": ["streetsidesoftware.code-spell-checker"]
    }
  },
  "forwardPorts": [3000]
}

注意：基於基礎映象中的內容，額外的配置將已新增到容器中。例如，我們在上面添加了 streetsidesoftware.code-spell-checker 擴充套件，並且容器還將包括 "dbaeumer.vscode-eslint"，因為它是 mcr.microsoft.com/devcontainers/typescript-node 的一部分。當使用 devcontainer.json 預構建時，這會自動發生，您可以在預構建部分瞭解更多資訊。

使用上述 devcontainer.json，您的開發容器已可用，您可以連線並開始在其中進行開發。嘗試使用Dev Containers: Reopen in Container命令

Quick pick with list of Dev Containers commands

執行此命令後，當 VS Code 重啟時，您現在將位於一個 Node.js 和 TypeScript 開發容器中，埠 3000 已轉發，並且 ESLint 擴充套件已安裝。連線後，注意狀態列左側的綠色遠端指示器，表示您已連線到開發容器。

VS Code instance connected to dev container

其他開發容器場景

透過 devcontainer.json 檔案，您可以

啟動一個獨立的容器來隔離您的工具鏈或加快設定速度。
使用由映象、Dockerfile 或Docker Compose 定義的已部署應用程式的容器。
從開發容器內部使用 Docker 或 Kubernetes來構建和部署您的應用程式。

如果 devcontainer.json 支援的工作流不滿足您的需求，您也可以附加到已執行的容器。

提示：想使用遠端 Docker 主機？請參閱在遠端 Docker 主機上開發一文以瞭解設定詳細資訊。

安裝其他軟體

您可能希望在開發容器中安裝其他軟體。一旦 VS Code 連線到容器，您就可以開啟 VS Code 終端並在容器內的作業系統上執行任何命令。這使您可以安裝新的命令列實用程式，並在 Linux 容器內啟動資料庫或應用程式服務。

大多數容器映象基於 Debian 或 Ubuntu，其中 apt 或 apt-get 命令用於安裝新軟體包。您可以在 Ubuntu 的文件中瞭解有關該命令的更多資訊。Alpine 映象包含一個類似的 apk 命令，而 CentOS / RHEL / Oracle SE / Fedora 映象使用 yum 或最近使用 dnf。

您要安裝的軟體的文件通常會提供具體的說明，但如果您在容器中以 root 使用者身份執行，則可能不需要在命令前加上 sudo。

例如

# If running as root
apt-get update
apt-get install <package>

如果您以 root 使用者身份執行，只要您的容器中配置了 sudo，您就可以安裝軟體。所有預定義的容器都設定了 sudo，但是將非 root 使用者新增到容器文章可以幫助您為自己的容器設定此項。無論如何，如果您安裝和配置了 sudo，您在以任何使用者（包括 root）身份執行時都可以使用它。

# If sudo is installed and configured
sudo apt-get update
sudo apt-get install <package>

假設您想安裝 Git。您可以在 VS Code 的整合終端中執行以下命令

# If sudo is installed and configured
sudo apt-get update
# Install Git
sudo apt-get install git

您也可以在 devcontainer.json 中使用 "features" 屬性從預定義的功能集合中安裝工具和語言，甚至可以安裝您自己的。

例如，您可以使用以下方式安裝最新版本的 Azure CLI

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

有關更多詳細資訊，請參閱Dev Container Features 規範。

重新構建

在編輯 .devcontainer 資料夾的內容時，您需要重新構建才能使更改生效。請使用Dev Containers: Rebuild Container命令來更新您的容器。

但是，如果您重新構建容器，您將不得不重新安裝任何手動安裝的內容。為避免此問題，您可以使用 devcontainer.json 中的 postCreateCommand 屬性或自定義 Dockerfile。

自定義 Dockerfile 將受益於 Docker 的構建快取，並且比 postCreateCommand 更快地進行重建。但是，Dockerfile 在開發容器建立和工作區資料夾掛載之前執行，因此無法訪問工作區資料夾中的檔案。Dockerfile 最適合安裝與工作區檔案無關的軟體包和工具。

postCreateCommand 操作在容器建立後執行，因此您也可以使用該屬性來執行諸如 npm install 之類的命令，或者在原始碼樹中執行 shell 指令碼（如果您已掛載它）。

"postCreateCommand": "bash scripts/install-dependencies.sh"

您還可以使用互動式 bash shell，以便您的 .bashrc 被載入，自動為您的環境自定義 shell。

"postCreateCommand": "bash -i scripts/install-dependencies.sh"

像 NVM 這樣的工具在不使用 -i 將 shell 置於互動模式的情況下將無法工作。

"postCreateCommand": "bash -i -c 'nvm install --lts'"

命令需要退出，否則容器將無法啟動。例如，如果您在 postCreateCommand 中添加了應用程式啟動項，則該命令將不會退出。

還有一個 postStartCommand，它會在每次容器啟動時執行。引數的行為與 postCreateCommand 完全相同，但命令在啟動時執行而不是建立時執行。

與其直接在 devcontainer.json 中引用映象或透過 postCreateCommand 或 postStartCommand 安裝軟體，不如使用 Dockerfile 是一種更有效的方法。

Dockerfile

Dockerfile 也將位於 .devcontainer 資料夾中。您可以將 devcontainer.json 中的 image 屬性替換為 dockerfile。

{
  "build": { "dockerfile": "Dockerfile" },

  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  },

  "forwardPorts": [3000]
}

當您進行安裝新軟體等更改時，即使重新構建開發容器，Dockerfile 中的更改也會保留。

在您的 Dockerfile 中，使用 FROM 指定映象，並使用 RUN 指令安裝任何軟體。您可以使用 && 將多個命令連線在一起。

FROM mcr.microsoft.com/devcontainers/javascript-node:0-18
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install git

注意：DEBIAN_FRONTEND 匯出可避免在您繼續使用容器時出現警告。

自動化開發容器建立

與其手動建立 .devcontainer，不如從命令面板（F1）中選擇Dev Containers: Add Dev Container Configuration Files...命令，它會將所需檔案作為起點新增到您的專案中，您可以根據需要進一步自定義。

該命令允許您根據資料夾的內容從列表中選擇預定義的容器配置。

Add a dev container config

您可以從中選擇的預定義容器配置來自我們的第一方和社群索引，這是Dev Container 規範的一部分。我們在 devcontainers/templates 倉庫中託管了一組作為規範一部分的模板。您可以瀏覽該倉庫的 src 資料夾以檢視每個模板的內容。

在完成使用Dev Containers: Add Dev Container Configuration Files...後，您將看到可用功能的列表，這些功能是您可以輕鬆新增到開發容器的工具和語言。Dev Containers: Configure Container Features 允許您更新現有配置。

Dev container features in Command Palette

您也可以重用現有的 Dockerfile。

Select Dockerfile

現在您已經有了 devcontainer.json 和 Dockerfile，讓我們來看看編輯容器配置檔案的通用流程。

完整的配置編輯迴圈

編輯容器配置很簡單。由於重新構建容器會“重置”容器至其初始內容（本地原始碼除外），因此如果您編輯容器配置檔案（devcontainer.json、Dockerfile 和 docker-compose.yml），VS Code 不會自動重新構建。取而代之的是，有幾個命令可用於簡化配置的編輯。

以下是使用這些命令的典型編輯迴圈

Container edit loop illustration

從命令面板（F1）中的Dev Containers: Add Dev Container Configuration Files...開始。
根據需要編輯 .devcontainer 資料夾的內容。
嘗試使用Dev Containers: Reopen in Container。
如果看到錯誤，請在出現的對話方塊中選擇Open Folder Locally。
視窗重新載入後，將在控制檯中顯示build log的副本，以便您調查問題。（如果您關閉了日誌，也可以使用Dev Containers: Show Container Log命令再次檢視日誌。）
執行Dev Containers: Rebuild and Reopen in Container，如有需要請跳轉到步驟 4。

如果您已經成功構建，當連線到容器時，您仍然可以根據需要編輯 .devcontainer 資料夾的內容，然後從命令面板（F1）中選擇Dev Containers: Rebuild Container，以使更改生效。

您也可以使用Dev Containers: Clone Repository in Container Volume命令來迭代您的容器。

從命令面板（F1）中的Dev Containers: Clone Repository in Container Volume開始。如果您輸入的倉庫中沒有 devcontainer.json，系統會提示您選擇一個起點。
根據需要編輯 .devcontainer 資料夾的內容。
嘗試使用Dev Containers: Rebuild Container。
如果看到錯誤，請在出現的對話方塊中選擇Open in Recovery Container。
在此“恢復容器”中，根據需要編輯 .devcontainer 資料夾的內容。
如果仍然遇到問題，請使用Dev Containers: Reopen in Container並跳轉到步驟 4。

使用 Docker Compose

在某些情況下，單一容器環境是不夠的。假設您想在配置中新增另一個複雜的元件，例如資料庫。您可以嘗試直接將其新增到 Dockerfile 中，或者透過附加容器來新增。幸運的是，Dev Containers 支援Docker Compose管理的多個容器配置。

您可以

使用現有的、未修改的 docker-compose.yml 中定義的 خدمة。
建立一個新的 docker-compose.yml（或複製現有檔案）來開發一個服務。
擴充套件現有的 Docker Compose 配置來開發服務。
使用單獨的 VS Code 視窗同時處理多個 Docker Compose 定義的服務。

注意： 當使用 Alpine Linux 容器時，某些擴充套件可能無法工作，因為擴充套件內部的原生代碼存在 glibc 依賴項。

VS Code 可以配置為自動啟動特定 Docker Compose 檔案中任何必需的容器。如果您已經使用命令列啟動了配置的容器，VS Code 將附加到正在執行的指定服務。這為您的多容器工作流提供了與上述 Docker 映象和 Dockerfile 工作流相同的快速設定優勢，同時仍允許您選擇使用命令列。

為了快速上手，請在 VS Code 中開啟您要處理的資料夾，然後在命令面板（F1）中執行Dev Containers: Add Dev Container Configuration Files...命令。

您將被提示從我們第一方和社群索引中選擇一個預定義的容器配置，該索引將根據您的資料夾內容進行過濾和排序。在 VS Code UI 中，您可以選擇以下模板之一作為 Docker Compose 的起點

現有 Docker Compose - 包含一組檔案，您可以將其放入現有專案中，這些檔案將重用專案根目錄中的 docker-compose.yml 檔案。
Node.js & MongoDB - 一個 Node.js 容器，連線到另一個容器中的 MongoDB 資料庫。
Python & PostgreSQL - 一個 Python 容器，連線到另一個容器中的 PostgreSQL。
Docker-Outside-of-Docker Compose - 包含 Docker CLI 並說明如何透過卷掛載 Docker Unix 套接字來從開發容器內部訪問本地 Docker 安裝。

選擇後，VS Code 會將相應的 .devcontainer/devcontainer.json（或 .devcontainer.json）檔案新增到資料夾中。

您也可以手動建立配置。要重用未修改的 Docker Compose 檔案，可以在 .devcontainer/devcontainer.json 中使用 dockerComposeFile 和 service 屬性。

例如

{
  "name": "[Optional] Your project name here",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "the-name-of-the-service-you-want-to-work-with-in-vscode",
  "workspaceFolder": "/default/workspace/path/in/container/to/open",
  "shutdownAction": "stopCompose"
}

有關其他可用屬性（如 workspaceFolder 和 shutdownAction）的資訊，請參閱devcontainer.json 參考。

將 .devcontainer/devcontainer.json 檔案新增到資料夾後，請從命令面板（F1）執行Dev Containers: Reopen in Container命令（如果您尚未在容器中，請執行Dev Containers: Open Folder in Container...）。

如果容器尚未執行，VS Code 將在此示例中呼叫 docker-compose -f ../docker-compose.yml up。service 屬性指示 VS Code 應連線到 Docker Compose 檔案中的哪個服務，而不是應啟動哪個服務。如果您手動啟動了它們，VS Code 將連線到您指定的服務。

您也可以建立 Docker Compose 檔案的開發副本。例如，如果您有 .devcontainer/docker-compose.devcontainer.yml，您只需在 devcontainer.json 中更改以下行

"dockerComposeFile": "docker-compose.devcontainer.yml"

但是，更好的方法通常是避免複製 Docker Compose 檔案，而是透過另一個檔案擴充套件它。我們將在下一節擴充套件 Docker Compose 檔案中進行介紹。

為避免容器因預設容器命令失敗或退出而關閉，您可以按如下方式修改 devcontainer.json 中指定的服務對應的 Docker Compose 檔案

# Overrides default command so things don't shut down after the process ends.
command: /bin/sh -c "while sleep 1000; do :; done"

如果您尚未完成，可以使用Docker Compose 檔案中的 volumes 列表將本地原始碼繫結掛載到容器中。

例如

volumes:
  # Mounts the project folder to '/workspace'. The target path inside the container
  # should match what your application expects. In this case, the compose file is
  # in a sub-folder, so you will mount '..'. You would then reference this path as the
  # 'workspaceFolder' in '.devcontainer/devcontainer.json' so VS Code starts here.
  - ..:/workspace:cached

但是，在 Linux 上，當使用繫結掛載時，您可能需要設定並指定非 root 使用者，否則您建立的任何檔案都將是 root 使用者。有關詳細資訊，請參閱向開發容器新增非 root 使用者。要讓 VS Code 以不同的使用者身份執行，請將此新增到 devcontainer.json

"remoteUser": "your-user-name-here"

如果您希望所有程序都以不同的使用者身份執行，請將其新增到 Docker Compose 檔案中相應的服務。

user: your-user-name-here

如果您沒有為開發建立自定義 Dockerfile，您可能想在服務容器內安裝其他開發工具，如 curl。雖然這比將這些工具新增到容器映象效率低，但您也可以為此目的使用 postCreateCommand 屬性。

有關安裝軟體的資訊，請參閱安裝其他軟體，有關 postCreateCommand 屬性的資訊，請參閱devcontainer.json 參考。

如果您的應用程式是用 C++、Go、Rust 或其他使用 ptrace 式偵錯程式的語言構建的，您還需要將以下設定新增到您的 Docker Compose 檔案中

# Required for ptrace-based debuggers like C++, Go, and Rust
cap_add:
- SYS_PTRACE
security_opt:
- seccomp:unconfined

首次建立容器後，您需要執行Dev Containers: Rebuild Container命令，以使 devcontainer.json、Docker Compose 檔案或相關 Dockerfile 的更新生效。

在 Docker Compose 中使用 localhost

您可以在 docker-compose.yml 檔案中新增其他服務，如Docker 文件中所述。但是，如果您希望此服務中的任何內容在容器中的 localhost 上可用，或者希望在本地轉發服務，請確保在服務配置中新增以下行

# Runs the service on the same network as the database container, allows "forwardPorts" in devcontainer.json function.
network_mode: service:db

您可以在Node.js 和 MongoDB 示例開發容器中看到 network_mode: service:db 的示例。

為開發擴充套件您的 Docker Compose 檔案

引用現有的部署/非開發用途的 docker-compose.yml 有一些潛在的缺點。

例如

如果入口點關閉，Docker Compose 將關閉容器。這對於需要反覆重啟應用程式的除錯場景來說是個問題。
您也可能沒有將本地檔案系統對映到容器，或者沒有將埠暴露給您想訪問的資料庫等其他資源。
您可能需要將本地 .ssh 資料夾的內容複製到容器中，或者設定上面在 Docker Compose 中使用所述的 ptrace 選項。

您可以透過多個 docker-compose.yml 檔案來擴充套件您的整個 Docker Compose 配置，這些檔案將覆蓋或補充您的主檔案，從而解決這些和其他類似問題。

例如，考慮以下附加的 .devcontainer/docker-compose.extend.yml 檔案

version: '3'
services:
  your-service-name-here:
    volumes:
      # Mounts the project folder to '/workspace'. While this file is in .devcontainer,
      # mounts are relative to the first file in the list, which is a level up.
      - .:/workspace:cached

    # [Optional] Required for ptrace-based debuggers like C++, Go, and Rust
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined

    # Overrides default command so things don't shut down after the process ends.
    command: /bin/sh -c "while sleep 1000; do :; done"

同一個檔案可以根據需要提供其他設定，例如埠對映。要使用它，請按特定順序在原始 docker-compose.yml 檔案以及 .devcontainer/docker-compose.extend.yml 中進行引用

{
  "name": "[Optional] Your project name here",

  // The order of the files is important since later files override previous ones
  "dockerComposeFile": ["../docker-compose.yml", "docker-compose.extend.yml"],

  "service": "your-service-name-here",
  "workspaceFolder": "/workspace",
  "shutdownAction": "stopCompose"
}

VS Code 將在啟動任何容器時自動使用這兩個檔案。您也可以從命令列自行啟動，如下所示

docker-compose -f docker-compose.yml -f .devcontainer/docker-compose.extend.yml up

雖然 postCreateCommand 屬性允許您在容器內安裝其他工具，但在某些情況下，您可能希望有一個專門用於開發的 Dockerfile。您也可以使用此相同方法來引用專門用於開發的自定義 Dockerfile，而無需修改現有的 Docker Compose 檔案。例如，您可以按如下方式更新 .devcontainer/docker-compose.extend.yml

version: '3'
services:
  your-service-name-here:
      # Note that the path of the Dockerfile and context is relative to the *primary*
      # docker-compose.yml file (the first in the devcontainer.json "dockerComposeFile"
      # array). The sample below assumes your primary file is in the root of your project.
      build:
        context: .
        dockerfile: .devcontainer/Dockerfile
      volumes:
        - .:/workspace:cached
      command: /bin/sh -c "while sleep 1000; do :; done"

恭喜！您已在 Visual Studio Code 中配置了開發容器。繼續閱讀以瞭解如何與團隊成員和不同專案共享容器配置。

將配置檔案新增到倉庫

您可以透過將 devcontainer.json 檔案新增到原始碼控制中，輕鬆共享自定義的 Dev Container 模板。透過將這些檔案包含在您的倉庫中，任何在 VS Code 中開啟您倉庫本地副本的人都會被自動提示在容器中重新開啟該資料夾，前提是他們已安裝 Dev Containers 擴充套件。

Dev container configuration file reopen notification

除了讓您的團隊使用一致的環境和工具鏈之外，這還可以讓新貢獻者或團隊成員更快地提高工作效率。首次貢獻者需要更少的指導，並且在環境設定方面遇到的問題更少。

新增“在開發容器中開啟”徽章

您還可以為倉庫新增一個徽章或連結，以便使用者可以輕鬆地在 Dev Containers 中開啟您的專案。它將在必要時安裝 Dev Containers 擴充套件，將倉庫克隆到容器卷中，並啟動開發容器。

例如，一個用於開啟 https://github.com/microsoft/vscode-remote-try-java 的徽章看起來像這樣

[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java)

您也可以直接包含一個“在開發容器中開啟”連結。

If you already have VS Code and Docker installed, you can click the badge above or [here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java) to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use.

替代方案：倉庫配置資料夾

在某些情況下，您可能希望為不屬於您控制的倉庫建立配置，或者您不希望在倉庫本身中包含配置。為了處理這種情況，您可以配置一個本地檔案系統位置來儲存配置，這些配置將根據倉庫自動拾取。

首先，在您的使用者設定中更新Dev > Containers: Repository Configuration Paths，指定您要用於儲存倉庫容器配置檔案的本地資料夾。

在設定編輯器中，您可以搜尋“dev containers repo”來找到該設定。

Repository container folders setting

接下來，將您的 .devcontainer/devcontainer.json（及相關檔案）放置在一個子資料夾中，該子資料夾應映象倉庫的遠端位置。例如，如果您想為 github.com/devcontainers/templates 建立一個配置，您將建立以下資料夾結構

📁 github.com
    📁 devcontainers
        📁 templates
           📁 .devcontainer

放置好後，當使用任何 Dev Containers 命令時，該配置都會自動拾取。進入容器後，您還可以從命令面板（F1）中選擇Dev Containers: Open Container Configuration File來開啟相關的 devcontainer.json 檔案並進行進一步編輯。

用於查詢配置的路徑是從 git remote -v 的輸出派生的。如果在嘗試在容器中重新開啟資料夾時未找到配置，請在命令面板（F1）中檢視日誌Dev Containers: Show Container Log，以獲取已檢查路徑的列表。

後續步驟

附加到正在執行的容器 - 附加到已在執行的 Docker 容器。
高階容器 - 查詢高階容器場景的解決方案。
devcontainer.json 參考 - 檢視 devcontainer.json 模式。

12/10/2025