編輯

建立開發容器

Name: Visual Studio Code
Author: Microsoft

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

建立開發容器的路徑

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

建立 devcontainer.json，它描述了 VS Code 如何啟動容器以及連線後需要做什麼。
透過使用 Dockerfile 來製作並持久化開發容器的更改，例如安裝新軟體。
透過 Docker Compose 配置多個容器。
進行更改後，構建你的開發容器以確保更改生效。

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

注意：開發容器擴充套件有一個 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 的起點。映象就像一個迷你磁碟驅動器，預裝了各種工具和作業系統。你可以從容器登錄檔拉取映象，登錄檔是儲存映象的倉庫集合。這是一個簡單的 devcontainer.json 示例，它使用預構建的 TypeScript 和 Node.js VS Code 開發容器映象

{
  "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" 屬性，從預定義的一組 Features 甚至是你自己的 Features 中安裝工具和語言。

例如，你可以使用以下命令安裝最新版本的 Azure CLI

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

有關更多詳細資訊，請參閱開發容器特性規範。

重建

編輯 .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 中用 dockerfile 替換 image 屬性

{
  "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

您可以從中選擇的預定義容器配置來自我們的第一方和社群索引，它是開發容器規範的一部分。我們在 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。
視窗重新載入後，控制檯中將顯示一份構建日誌副本，以便你調查問題。根據需要編輯 .devcontainer 資料夾的內容。（如果你關閉了日誌，也可以使用 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 中，或者透過額外的容器新增。幸運的是，開發容器支援 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 - 一個連線到不同容器中 MongoDB 資料庫的 Node.js 容器。
Python 和 PostgreSQL - 一個連線到不同容器中 PostgreSQL 的 Python 容器。
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 檔案。我們將在下一節介紹擴充套件 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:
  # 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 文件中的說明將其他服務新增到 docker-compose.yml 檔案中。但是，如果你希望此服務中執行的任何內容在容器的 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 檔案新增到原始碼管理中，輕鬆地為你的專案共享自定義的開發容器模板。透過在你的倉庫中包含這些檔案，任何在 VS Code 中開啟你倉庫的本地副本的人都將自動收到提示，要求在容器中重新開啟資料夾，前提是他們已安裝開發容器擴充套件。

Dev container configuration file reopen notification

除了團隊使用一致的環境和工具鏈的優勢外，這還使新的貢獻者或團隊成員更容易快速提高工作效率。首次貢獻者將需要更少的指導，並減少與環境設定相關的問題。

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

你也可以在你的倉庫中新增徽章或連結，以便使用者可以輕鬆地在開發容器中開啟你的專案。它將安裝開發容器擴充套件（如果需要），將倉庫克隆到容器卷中，並啟動開發容器。

例如，開啟 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)

您也可以直接包含一個 open in dev container 連結

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

一旦到位，在使用任何開發容器命令時，配置將自動被拾取。進入容器後，你還可以從命令面板 (F1) 中選擇 Dev Containers: Open Container Configuration File 以開啟相關的 devcontainer.json 檔案並進行進一步編輯。

用於查詢配置的路徑來自 git remote -v 的輸出。如果你嘗試在容器中重新開啟資料夾時未找到配置，請檢查命令面板 (F1) 中的 Dev Containers: Show Container Log 日誌，檢視已檢查的路徑列表。

後續步驟

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

09/11/2025