主题

规范

开发容器元数据参考

devcontainer.json 文件包含配置特定开发容器所需的任何必要元数据和设置，以供指定的工具和运行时堆栈使用。它可被支持开发容器规范的工具和服务用来创建包含一个或多个开发容器的开发环境。

标记有 🏷️️ 的元数据属性除了可以存储在 devcontainer.json 中外，还可以存储在 devcontainer.metadata 容器镜像标签 中。此标签可以包含一个 JSON 片段数组，当创建容器时，这些片段会自动与 devcontainer.json 的内容（如有）合并。

通用的 devcontainer.json 属性

属性	类型	描述
`name`	string	在 UI 中显示的开发容器名称。
`forwardPorts` 🏷️	数组	一个应始终从主容器内部转发到本地机器（包括在 Web 上）的端口号或 `"host:port"` 值数组（例如 `[3000, "db:5432"]`）。该属性对于转发那些无法自动转发的端口最有用，原因包括：相关进程在 `devcontainer.json` 支持服务/工具连接之前启动，或者在 Docker Compose 场景中转发不在主容器内的服务（例如 `"db:5432"`）。默认值为 `[]`。
`portsAttributes` 🏷️	对象	将端口号、`"host:port"` 值、范围或正则表达式映射到一组默认选项的对象。有关可用选项，请参阅端口属性。例如： `"portsAttributes": {"3000": {"label": "Application port"}}`
`otherPortsAttributes` 🏷️	对象	对于未配置 `portsAttributes` 的端口、端口范围和主机的默认选项。有关可用选项，请参阅端口属性。例如： `"otherPortsAttributes": {"onAutoForward": "silent"}`
`containerEnv` 🏷️	对象	一组用于设置或覆盖容器环境变量的名称-值对。值中可以引用环境变量和预定义变量。例如： `"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }` 如果您想在设置此变量时引用现有的容器变量（例如更新 `PATH`），请改用 `remoteEnv`。 `containerEnv` 将在 Docker 容器本身上设置该变量，因此容器中启动的所有进程都将能够访问它。但它在容器的生命周期内是静态的——您必须重建容器才能更新该值。我们建议尽可能使用 `containerEnv`（而不是 `remoteEnv`），因为它允许所有进程都能看到该变量，且不具有客户端特定性。
`remoteEnv` 🏷️	对象	一组用于设置或覆盖 `devcontainer.json` 支持服务/工具（或终端等子进程）环境变量的名称-值对，但不会覆盖整个容器的环境变量。值中可以引用环境变量和预定义变量。如果变量值不是静态的，您可能希望使用 `remoteEnv`（而不是 `containerEnv`），因为您可以更新其值而无需重建整个容器。
`remoteUser` 🏷️	string	覆盖 `devcontainer.json` 支持服务/工具在容器内运行所使用的用户（以及终端、任务或调试等子进程）。这不会更改容器整体运行所使用的用户（后者可通过 `containerUser` 设置）。默认为容器整体运行所使用的用户（通常是 `root`）。您可以从下方的 remoteUser 部分了解更多信息。
`containerUser` 🏷️	string	覆盖容器内运行所有操作的用户。默认为 `root` 或用于创建镜像的相关 Dockerfile 中的最后一个 `USER` 指令。如果您希望任何连接的工具或相关进程使用与容器不同的用户，请参阅 `remoteUser`。
`updateRemoteUserUID` 🏷️	boolean	在 Linux 上，如果指定了 `containerUser` 或 `remoteUser`，用户的 UID/GID 将被更新以匹配本地用户的 UID/GID，从而避免绑定挂载（bind mount）的权限问题。默认值为 `true`。
`userEnvProbe` 🏷️	enum	指示用于“探测”用户环境变量的 shell 类型，以便将其包含在 `devcontainer.json` 支持服务/工具的进程中：`none`、`interactiveShell`、`loginShell` 或 `loginInteractiveShell`（默认）。所使用的具体 shell 基于用户的默认 shell（通常为 bash）。例如，bash 交互式 shell 通常会包含在 `/etc/bash.bashrc` 和 `~/.bashrc` 中设置的变量，而登录 shell 通常包含来自 `/etc/profile` 和 `~/.profile` 的变量。将此属性设置为 `loginInteractiveShell` 将获取所有四个文件中的变量。
`overrideCommand` 🏷️	boolean	告诉 `devcontainer.json` 支持的服务/工具在启动容器时是否应运行 `/bin/sh -c "while sleep 1000; do :; done"`，而不是运行容器的默认命令（因为如果默认命令失败，容器可能会关闭）。如果容器要正常运行必须执行默认命令，请将其设置为 `false`。对于使用 Dockerfile 镜像的情况，默认值为 `true`；对于引用 Docker Compose 文件的情况，默认值为 `false`。
`shutdownAction` 🏷️	enum	指示 `devcontainer.json` 支持的工具在相关的工具窗口关闭或关闭时是否应停止容器。可选值为 `none`、`stopContainer`（镜像或 Dockerfile 的默认值）和 `stopCompose`（Docker Compose 的默认值）。
`init` 🏷️	boolean	默认值为 `false`。一种跨编排器的方式，用于指示是否应使用 tini init 进程来帮助处理僵尸进程。
`privileged` 🏷️	boolean	默认值为 `false`。一种跨编排器的方式，使容器以特权模式（`--privileged`）运行。对于 Docker-in-Docker 等场景是必需的，但具有安全隐患，特别是在直接在 Linux 上运行时。
`capAdd` 🏷️	数组	默认值为 `[]`。一种跨编排器的方式，用于添加通常对容器禁用的功能（capabilities）。最常用于添加调试 C++、Go 和 Rust 等语言所需的 `ptrace` 功能。例如： `"capAdd": ["SYS_PTRACE"]`
`securityOpt` 🏷️	数组	默认值为 `[]`。一种跨编排器的方式，用于设置容器安全选项。例如： `"securityOpt": [ "seccomp=unconfined" ]`
`mounts` 🏷️	字符串或对象	默认未设置。一种跨编排器的方式，用于向容器添加额外的挂载。每个值都是一个字符串，接受与 Docker CLI `--mount` 标志相同的值。值中可以引用环境变量和预定义变量。例如： `"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]`
`features`	对象	一个包含开发容器特性（Dev Container Features）ID 及其相关选项的对象，这些特性将被添加到您的主容器中。可用的具体选项因特性而异，请参阅其文档以了解详细信息。例如： `"features": { "ghcr.io/devcontainers/features/github-cli": {} }`
`overrideFeatureInstallOrder`	数组	默认情况下，特性会尝试根据每个特性中的 `installsAfter` 属性自动确定安装顺序。此属性允许您在需要时覆盖特性的安装顺序。例如： `"overrideFeatureInstallОrder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ]`
`customizations` 🏷️	对象	特定于产品的属性，在支持工具中定义。

场景特定属性

devcontainer.json 的重点是描述如何为开发目的丰富容器，而不是作为多容器编排格式。相反，当需要管理多个容器及其生命周期时，可以引用容器编排格式。目前，devcontainer.json 包含用于在没有容器编排器的情况下工作（通过直接引用镜像或 Dockerfile）以及使用 Docker Compose 作为简单的多容器编排器的场景特定属性。

镜像或 Dockerfile 特定属性

属性	类型	描述
`image`	string	使用镜像时必填。容器注册表（DockerHub、GitHub Container Registry、Azure Container Registry）中镜像的名称，`devcontainer.json` 支持的服务/工具应使用该名称来创建开发容器。
`build.dockerfile`	string	使用 Dockerfile 时必填。定义容器内容的 Dockerfile 的位置。该路径相对于 `devcontainer.json` 文件。
`build.context`	string	Docker 构建应从相对于 `devcontainer.json` 的路径运行。例如，值为 `".."` 将允许您引用同级目录中的内容。默认值为 `"."`。
`build.args`	对象	一组名称-值对，包含构建 Dockerfile 时应传递的 Docker 镜像构建参数。值中可以引用环境变量和预定义变量。默认未设置。例如：`"build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }`
`build.options`	数组	构建 Dockerfile 时应传递给构建命令的 Docker 镜像构建选项数组。默认值为 `[]`。例如：`"build": { "options": [ "--add-host=host.docker.internal:host-gateway" ] }`
`build.target`	string	一个字符串，指定构建 Dockerfile 时应传递的 Docker 镜像构建目标。默认未设置。例如：`"build": { "target": "development" }`
`build.cacheFrom`	字符串，数组	一个字符串或字符串数组，指定在构建镜像时用作缓存的一个或多个镜像。缓存的镜像标识符会通过 `--cache-from` 传递给 `docker build` 命令。
`appPort`	整数，字符串，数组	在大多数情况下，我们建议使用新的 forwardPorts 属性。此属性接受在容器运行时应在本地发布的端口或端口数组。与 `forwardPorts` 不同，您的应用程序可能需要监听所有接口（`0.0.0.0`）而不仅仅是 `localhost`，才能在外部访问。默认值为 `[]`。在此处了解更多关于端口发布与转发的信息：此处。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串属性与数组属性格式的信息。
`workspaceMount`	string	同时也需要设置 `workspaceFolder`。覆盖创建容器时工作区的默认本地挂载点。支持与 Docker CLI `--mount` 标志相同的值。值中可以引用环境变量和预定义变量。例如： `"workspaceMount": "source=${localWorkspaceFolder}/sub-folder,target=/workspace,type=bind,consistency=cached", "workspaceFolder": "/workspace"`
`workspaceFolder`	string	需要设置 `workspaceMount`。设置 `devcontainer.json` 支持的服务/工具在连接到容器时应打开的默认路径。默认值为自动源代码挂载位置。
`runArgs`	数组	运行容器时应使用的 Docker CLI 参数数组。默认值为 `[]`。例如，这允许 C++ 等基于 ptrace 的调试器在容器中工作： `"runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ]` .

Docker Compose 特定属性

属性	类型	描述
`dockerComposeFile`	字符串，数组	使用 Docker Compose 时必填。相对于 `devcontainer.json` 文件的 Docker Compose 文件路径或有序路径列表。当扩展 Docker Compose 配置时，使用数组很有用。数组的顺序很重要，因为后面文件的内容可以覆盖前面文件设置的值。默认的 `.env` 文件取自项目的根目录，但您可以在 Docker Compose 文件中使用 `env_file` 来指定备用位置。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串属性与数组属性格式的信息。
`service`	string	使用 Docker Compose 时必填。运行后 `devcontainer.json` 支持的服务/工具应连接的服务名称。
`runServices`	数组	Docker Compose 配置中应由 `devcontainer.json` 支持的服务/工具启动的服务数组。除非 `"shutdownAction"` 为 `"none"`，否则在您断开连接时，这些服务也会被停止。默认值为所有服务。
`workspaceFolder`	string	设置 `devcontainer.json` 支持的服务/工具在连接到容器时应打开的默认路径（通常是容器中可以找到源代码的卷挂载路径）。默认值为 `"/"`。

工具特定属性

虽然大多数属性适用于任何支持 devcontainer.json 的工具或服务，但有一些是特定于某些工具的。您可以在支持工具和服务文档中探索这一点。

生命周期脚本

创建或使用开发容器时，您可能需要在容器生命周期的不同点运行不同的命令。下表列出了一组命令属性，您可以使用它们按运行顺序更新容器内容（例如，onCreateCommand 将在 initializeCommand 之后运行）。每个命令属性都是一个字符串或应该从 workspaceFolder 执行的命令参数列表。

属性	类型	描述
`initializeCommand`	字符串，数组，对象	在初始化期间（包括容器创建期间和随后的启动期间）在主机上运行的命令字符串或命令参数列表。该命令在给定的会话期间可能会运行多次。 ⚠️ 命令在主机上源代码所在的任何位置运行。对于云服务，这在云中。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`onCreateCommand` 🏷️	字符串，数组，对象	此命令是创建开发容器时完成容器设置的三个命令（连同 `updateContentCommand` 和 `postCreateCommand`）中的第一个。它和后续命令在容器首次启动后立即在容器内执行。云服务在缓存或预构建容器时可以使用此命令。这意味着它通常无法访问用户范围的资产或密钥。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`updateContentCommand` 🏷️	字符串，数组，对象	此命令是创建开发容器时完成容器设置的三个命令中的第二个。它在创建过程中每当源代码树中有新内容时，在 `onCreateCommand` 之后在容器内执行。它将至少执行一次，但云服务也会定期执行该命令以刷新缓存或预构建的容器。与使用 `onCreateCommand` 的云服务一样，它只能利用仓库和组织范围的密钥或权限。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`postCreateCommand` 🏷️	字符串，数组，对象	此命令是创建开发容器时完成容器设置的三个命令中的最后一个。它发生在 `updateContentCommand` 之后，并且开发容器首次分配给用户之后。云服务可以使用此命令利用特定于用户的密钥和权限。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`postStartCommand` 🏷️	字符串，数组，对象	每次容器成功启动时运行的命令。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`postAttachCommand` 🏷️	字符串，数组，对象	每次工具有成功连接到容器时运行的命令。请注意，数组语法将在不使用 shell 的情况下执行命令。您可以了解更多关于字符串、数组与对象属性格式的信息。
`waitFor` 🏷️	enum	一个枚举，指定任何工具在连接前应等待的命令。默认值为 `updateContentCommand`。这允许您将 `onCreateCommand` 或 `updateContentCommand` 用于 `devcontainer.json` 支持的工具连接之前必须发生的步骤，同时仍将 `postCreateCommand` 用于之后可以在后台发生的步骤。

对于每个命令属性，如果值是单个字符串，它将在 /bin/sh 中运行。在字符串中使用 && 执行多个命令。例如，"yarn install" 或 "apt-get update && apt-get install -y curl"。数组语法 ["yarn", "install"] 将直接调用命令（在本例中为 yarn），而不使用 shell。每个命令都在源代码挂载后触发，因此您也可以从源代码树运行 shell 脚本。例如：bash scripts/install-dev-tools.sh。

如果生命周期脚本中的任何一个失败，任何后续脚本将不会执行。例如，如果 postCreateCommand 失败，postStartCommand 及后续的任何脚本都将被跳过。

最低主机要求

虽然 devcontainer.json 不关注硬件或虚拟机配置，但了解容器的最低 RAM、CPU 和存储要求可能会有所帮助。这就是 hostRequirements 属性允许您做的事情。云服务可以使用这些属性自动默认为可用的最佳计算选项，而在其他情况下，如果不满足要求，您会看到警告。

属性	类型	描述
`hostRequirements.cpus` 🏷️	整数	指示最低要求的 CPU/虚拟 CPU/核心数量。例如：`"hostRequirements": {"cpus": 2}`
`hostRequirements.memory` 🏷️	string	一个字符串，指示带有 `tb`、`gb`、`mb` 或 `kb` 后缀的最低内存要求。例如：`"hostRequirements": {"memory": "4gb"}`
`hostRequirements.storage` 🏷️	string	一个字符串，指示带有 `tb`、`gb`、`mb` 或 `kb` 后缀的最低存储要求。例如：`"hostRequirements": {"storage": "32gb"}`
`hostRequirements.gpu` 🏷️	布尔值，字符串，对象	指示是否需要 GPU。布尔值指示是否需要 GPU。字符串 `"optional"` 指示在可用时使用 GPU，但不是必需的。对象语法指定需要多少 GPU 资源。`cores` 属性指示最少核心数，`memory` 属性指示带有 `tb`、`gb`、`mb` 或 `kb` 后缀的最低存储要求。例如：`"gpu": { "cores": 1000, "storage": "32gb" }`

端口属性

portsAttributes 和 otherPortsAttributes 属性允许您为一个或多个手动或自动转发的端口映射默认端口选项。以下是可以设置在分配给该属性的配置对象中的选项列表。

属性	类型	描述
`label` 🏷️	string	端口视图中端口的显示名称。默认未设置。
`protocol` 🏷️	enum	控制转发端口的协议处理。未设置时，假定该端口是原始 TCP 流，如果转发到 `localhost`，它支持任意数量的协议。但是，如果端口转发到 Web URL（例如从云上的云服务），则仅支持容器中的 HTTP 端口。将此属性设置为 `https` 会通过忽略在端口上通信时出现的任何 SSL/TLS 证书，并改用转发 URL 的正确证书（例如 `https://*.githubpreview.dev`）来更改处理。如果设置为 `http`，则处理方式与未设置协议时相同。默认未设置。
`onAutoForward` 🏷️	enum	控制当您连接到容器后端口自动转发时应发生的情况。`notify` 是默认设置，端口自动转发时会显示通知。如果设置为 `openBrowser`，端口将在系统的默认浏览器中打开。`openBrowserOnce` 的值将只打开一次浏览器。`openPreview` 将在 `devcontainer.json` 支持的服务/工具的嵌入式预览浏览器中打开 URL。`silent` 值将转发端口，但不采取进一步行动。`ignore` 值意味着该端口根本不应该被自动转发。
`requireLocalPort` 🏷️	boolean	规定是否必须将容器中的端口映射到本地的相同端口。如果设置为 `false`，`devcontainer.json` 支持的服务/工具将尝试使用指定的端口转发到 `localhost`，如果不可用，则静默映射到另一个端口。如果设置为 `true`，则在无法使用相同端口时会收到通知。默认值为 `false`。
`elevateIfNeeded` 🏷️	boolean	在某些操作系统上，将 22、80 或 443 等低端口从 `devcontainer.json` 支持的服务/工具转发到 `localhost` 上的同一端口可能需要提升的权限。将此属性设置为 `true` 将在这种情况下自动尝试提升 `devcontainer.json` 支持工具的权限。默认值为 `false`。

字符串与数组属性格式

某些属性的格式将根据 shell 的参与情况而有所不同。

postCreateCommand、postStartCommand、postAttachCommand 和 initializeCommand 都有 3 种类型：

数组：传递给操作系统执行，无需经过 shell
字符串：经过 shell（需要解析为命令和参数）
对象：所有生命周期脚本都已扩展为支持 object 类型，以允许并行执行

runArgs 只有数组类型。通过典型的命令行使用 runArgs 时，如果 shell 遇到带有空格的参数，您将需要单引号。但是，这些单引号不会传递给可执行文件。因此，在 devcontainer.json 中，您应遵循数组格式并省略单引号。

"runArgs": ["--device-cgroup-rule=my rule here"]

而不是

"runArgs": ["--device-cgroup-rule='my rule here'"]

我们也可以比较 postAttachCommand 的字符串、数组和对象版本。您可以使用以下字符串格式，它将删除单引号作为 shell 解析的一部分。

"postAttachCommand": "echo foo='bar'"

相比之下，数组格式将保留单引号并将它们写入标准输出（您可以在开发容器日志中看到输出）。

"postAttachCommand": ["echo", "foo='bar'"]

最后，您可以使用对象格式。

{
  "postAttachCommand": {
    "server": "npm start",
    "db": ["mysql", "-u", "root", "-p", "my database"]
  }
}

devcontainer.json 中的变量

devcontainer.json 中的某些字符串值可以引用变量，格式如下：${variableName}。以下是您可以使用的可用变量列表。

变量	属性	描述
`${localEnv:VARIABLE_NAME}`	任意	主机上的环境变量值（在下例中称为 `VARIABLE_NAME`）。未设置的变量留空。 ⚠️ 客户端（如 VS Code）可能需要重启才能获取新设置的变量。 ⚠️ 对于云服务，主机位于云中，而不是您的本地机器。示例 1. 设置一个包含您在 Linux / macOS 上的本地主文件夹或 Windows 上的用户文件夹的变量 `"remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" }`. 当环境变量未设置时，可以使用 `${localEnv:VARIABLE_NAME:default_value}` 提供默认值。 2. 在 macOS 的现代版本中，默认配置允许通过命令 `echo 'export VARIABLE_NAME=my-value' >> ~/.zshenv` 设置本地变量。
`${containerEnv:VARIABLE_NAME}`	`remoteEnv`	容器启动并运行后，容器内现有环境变量的值（在本例中称为 `VARIABLE_NAME`）。例如： `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` 当环境变量未设置时，可以使用 `${containerEnv:VARIABLE_NAME:default_value}` 提供默认值。
`${localWorkspaceFolder}`	任意	在 `devcontainer.json` 支持的服务/工具中打开的本地文件夹路径（包含 `.devcontainer/devcontainer.json`）。
`${containerWorkspaceFolder}`	任意	可以在容器中找到工作区文件的路径。
`${localWorkspaceFolderBasename}`	任意	在 `devcontainer.json` 支持的服务/工具中打开的本地文件夹名称（包含 `.devcontainer/devcontainer.json`）。
`${containerWorkspaceFolderBasename}`	任意	可以在容器中找到工作区文件的文件夹名称。
`${devcontainerId}`	任意	允许特性引用一个对于安装它们的开发容器唯一且在重建过程中保持稳定的标识符。在 devcontainer.json 中支持它的属性有：`name`、`runArgs`、`initializeCommand`、`onCreateCommand`、`updateContentCommand`、`postCreateCommand`、`postStartCommand`、`postAttachCommand`、`workspaceFolder`、`workspaceMount`、`mounts`、`containerEnv`、`remoteEnv`、`containerUser`、`remoteUser` 和 `customizations`。