尝试以扩展 VS Code 中的代理模式！

Dev Containers 教程

本教程将引导您使用 Docker 容器和 Dev Containers 扩展在 Docker 容器中运行 Visual Studio Code。完成本教程无需 Docker 先验知识。

在 Docker 容器**内**运行 VS Code 有诸多益处，但在此演练中，我们将重点介绍如何使用 Docker 容器搭建一个与本地环境隔离的开发环境。

先决条件

您需要安装 Visual Studio Code。

安装 Docker

需要 Docker 来创建和管理容器。

Docker Desktop

下载并安装 Docker Desktop，或者选择其他 Docker 选项，例如在远程主机上使用 Docker 或符合 Docker 规范的 CLI。

启动 Docker

运行 Docker Desktop 应用程序以启动 Docker。如果您的活动托盘中出现 Docker 鲸鱼图标，则表示它正在运行。

Docker 可能需要几分钟才能启动。如果鲸鱼图标正在动画，则它可能仍在启动过程中。您可以点击该图标查看状态。

Docker status

检查 Docker

Docker 运行后，您可以打开一个新的终端窗口并输入命令来确认一切正常。

docker --version
# Docker version 18.09.2, build 6247962

安装扩展

Dev Containers 扩展允许您在 Docker 容器中运行 Visual Studio Code。

安装 Dev Containers 扩展

Dev Containers extension

检查安装

安装 Dev Containers 扩展后，您会在状态栏最左侧看到一个新的状态栏项。

Remote Status bar item

远程状态栏项可以快速显示 VS Code 正在哪个上下文（本地或远程）中运行，点击该项会弹出 Dev Containers 命令。

Dev Containers commands

获取示例

为了创建一个 Docker 容器，我们将打开一个包含 Node.js 项目的 GitHub 仓库。

打开命令面板 (F1) 运行命令 Dev Containers: 尝试 Dev Container 示例... 并从列表中选择 Node 示例。

Select a sample from the list

注意：还有其他开发容器示例，例如 vscode-remote-try-python 或 vscode-remote-try-java，但本教程将使用 vscode-remote-try-node。

等待容器构建

窗口将重新加载，但由于容器尚不存在，VS Code 将创建一个容器并将示例仓库克隆到一个独立的 容器卷 中。这可能需要一些时间，进度通知将提供状态更新。幸运的是，下次您打开此文件夹时，无需再执行此步骤，因为容器将已存在。

Dev Container Progress Notification

容器构建完成后，VS Code 会自动连接到它，并将您的本地文件系统中的项目文件夹映射到容器中。

检查容器

容器运行并连接后，您应该会在状态栏的左下方看到远程上下文的变化。

Building image

检查你的环境

在容器中开发的一大好处是，您可以使用应用程序所需的特定版本的依赖项，而不会影响您的本地开发环境。

本教程所用的特定容器已安装 Node.js v18，您可以通过打开一个新终端：终端 > 新建终端 (⌃⇧` (Windows, Linux Ctrl+Shift+`)) 并输入以下内容来检查。

node --version; npm --version

这应该会显示以下版本：

Node.js version check

运行应用程序

现在我们可以按下 F5，这将在容器内运行应用程序。进程启动后，导航到 https://:3000，您应该会看到简单的 Node.js 服务器正在运行！

Running the application

结束容器连接

您可以通过 文件 > 关闭远程连接 结束容器中的会话，并返回到本地运行 VS Code。

工作原理

下一节将更详细地描述 Dev Containers 扩展如何设置和配置您的容器。

Dev Containers 扩展使用 .devcontainer 文件夹中的文件，即 devcontainer.json，以及可选的 Dockerfile 或 docker-compose.yml 来创建您的开发容器。

在我们刚刚探索的示例中，项目包含一个 .devcontainer 文件夹，其中有一个 devcontainer.json 文件。devcontainer.json 使用镜像 mcr.microsoft.com/devcontainers/javascript-node:0-18。您可以在 devcontainers/images 仓库中更详细地了解此镜像。

首先，您的镜像会根据提供的 Dockerfile 或镜像名称构建，在此示例中为 mcr.microsoft.com/devcontainers/javascript-node:0-18。然后使用 devcontainer.json 中的一些设置创建并启动容器。最后，您的 Visual Studio Code 环境会根据 devcontainer.json 中的设置再次安装和配置。例如，此示例中的开发容器会安装 streetsidesoftware.code-spell-checker 扩展。

注意：容器将根据基础镜像中的内容自动添加额外的配置。例如，我们在上面看到了 streetsidesoftware.code-spell-checker 扩展，容器还将包含 "dbaeumer.vscode-eslint"，因为它是 mcr.microsoft.com/devcontainers/typescript-node 的一部分。这在使用 devcontainer.json 进行预构建时会自动发生，您可以在预构建部分了解更多信息。

完成所有这些操作后，您的本地 Visual Studio Code 副本将连接到在新开发容器中运行的 Visual Studio Code 服务器。

Architecture

devcontainer.json

devcontainer.json 本质上是一个配置文件，它决定了您的开发容器如何构建和启动。

//devcontainer.json
{
  "name": "Node.js",

  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",

  // Features to add to the dev container. More info: https://containers.dev/features.
  // "features": {},

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

  // "forwardPorts": [3000],

  "portsAttributes": {
    "3000": {
      "label": "Hello Remote World",
      "onAutoForward": "notify"
    }
  },

  "postCreateCommand": "yarn install"

  // "remoteUser": "root"
}

上述示例摘自我们在教程中使用的 vscode-remote-try-node 仓库。

选项 描述
image 容器注册表（Docker Hub、GitHub Container Registry、Azure Container Registry）中 VS Code 应用于创建开发容器的镜像名称。
dockerfile 您可以使用 dockerfile 属性代替引用 image，该属性是您希望用作镜像的 Dockerfile 的相对路径。
features 要添加的 Dev Container Feature ID 及其相关选项的对象。
customizations 配置特定于工具的属性，例如 VS Code 的 settings 和 extensions 属性。
settings 将默认的 settings.json 值添加到容器/机器特定的设置文件，例如 "terminal.integrated.defaultProfile.linux": "bash"。
extensions 一个扩展 ID 数组，指定在创建容器时应安装在容器内的扩展。
forwardPorts 使容器内的端口列表在本地可用。
portsAttributes 为特定转发端口设置默认属性。
postCreateCommand 容器创建后要运行的命令字符串或命令参数列表。
remoteUser 覆盖 VS Code 在容器中运行时（以及子进程）的用户。默认为 containerUser。

您可以查看 devcontainer.json 选项的完整列表。

恭喜

恭喜，你已成功完成本教程！

这只是对使用开发容器可能实现的简要概述。下一步，我们建议您查看如何从您的机器在容器中打开现有文件夹，或者在容器中打开 GitHub 仓库或 PR。

查看其他远程开发扩展。

或者通过安装远程开发扩展包获取所有这些扩展。

故障排除

验证 Docker 上下文

如果您使用的不是全新的 Docker 安装，并且 Dev Containers: 尝试 Dev Container 示例... 示例在当前上下文中遇到问题，您应该检查您的 Docker 上下文。全新安装将具有“default”上下文，您可以将其设置回当前上下文。

# Displays the list of contexts, '*' denotes the current context
docker context list

# Switches the list to the 'default' context
docker context use default
07/09/2025