Topics

规格

Dev Containers 元数据参考

该文件包含为给定的明确定义的工具和运行时堆栈配置 Dev Containers devcontainer.json所需的任何元数据和设置。支持 Dev Containers 规范的工具和服务可以使用它来创建包含一个或多个 Dev Containers 的开发环境。

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

常规 devcontainer.json 属性

财产	类型	描述
`name`	细绳	UI 中显示的 Dev Containers 的名称。
`forwardPorts`???️	大批	应始终从主容器内部转发到本地计算机（包括在 Web 上）的端口号或值数组`"host:port"`（例如）。`[3000, "db:5432"]`该属性对于转发无法自动转发的端口最有用，因为相关进程在`devcontainer.json`支持服务/工具连接之前启动，或者用于在 Docker Compose 场景中转发不在主容器中的服务（例如`"db:5432"`）。默认为`[]`.
`portsAttributes`???️	目的	将端口号、`"host:port"`值、范围或正则表达式映射到一组默认选项的对象。有关可用选项，请参阅端口属性。例如： `"portsAttributes": {"3000": {"label": "Application port"}}`
`otherPortsAttributes`???️	目的	未使用 .config 配置的端口、端口范围和主机的默认选项`portsAttributes`。有关可用选项，请参阅端口属性。例如： `"otherPortsAttributes": {"onAutoForward": "silent"}`
`containerEnv`???️	目的	一组名称/值对，用于设置或覆盖容器的环境变量。值中可以引用环境变量和预定义变量。例如： `"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }` 如果您想在设置此变量时引用现有容器变量（例如更新`PATH`），请改用`remoteEnv`。 `containerEnv`将在 Docker 容器本身上设置该变量，因此容器中生成的所有进程都可以访问它。但它在容器的生命周期内也将是静态的 - 您必须重建容器才能更新该值。我们建议尽可能多地使用`containerEnv`(over )，因为它允许所有进程查看该变量并且不是特定于客户端的。`remoteEnv`
`remoteEnv`???️	目的	一组名称-值对，用于设置或覆盖`devcontainer.json`支持服务/工具（或终端等子流程）的环境变量，但不覆盖整个容器。值中可以引用环境变量和预定义变量。如果该值不是静态的，您可能需要使用`remoteEnv`(over )，因为您可以更新其值而无需重建整个容器。`containerEnv`
`remoteUser`???️	细绳	覆盖支持服务工具/在容器中运行的用户`devcontainer.json`（以及终端、任务或调试等子进程）。不更改容器作为整体运行的用户，可以使用进行设置`containerUser`。默认为整个容器运行的用户（通常`root`）。您可以在下面的远程用户部分了解更多信息。
`containerUser`???️	细绳	覆盖在容器内运行的所有操作的用户。默认为用于创建映像的相关 Dockerfile 中的任一指令`root`或最后一条指令。`USER`如果您希望任何连接的工具或相关进程使用与容器不同的用户，请参阅`remoteUser`。
`updateRemoteUserUID`???️	布尔值	在 Linux 上，如果指定了`containerUser`或`remoteUser`，则用户的 UID/GID 将被更新以匹配本地用户的 UID/GID 以避免绑定安装的权限问题。默认为`true`.
`userEnvProbe`???️	枚举	指示用于“探测”用户环境变量以包含在`devcontainer.json`支持服务/工具进程中的 shell 类型：`none`、`interactiveShell`、`loginShell`或`loginInteractiveShell`（默认）。使用的特定 shell 基于用户的默认 shell（通常是 bash）。例如，bash 交互式 shell 通常包含在`/etc/bash.bashrc`和中设置的变量`~/.bashrc`，而登录 shell 通常包含来自`/etc/profile`和的变量`~/.profile`。将此属性设置为`loginInteractiveShell`将从所有四个文件中获取变量。
`overrideCommand`???️	布尔值	告诉`devcontainer.json`支持服务/工具它们是否应该`/bin/sh -c "while sleep 1000; do :; done"`在启动容器时运行，而不是容器的默认命令（因为如果默认命令失败，容器可以关闭）。设置为`false`是否必须运行默认命令才能使容器正常运行。`true`使用镜像 Dockerfile 和`false`引用 Docker Compose 文件时默认为for。
`shutdownAction`???️	枚举	指示当`devcontainer.json`相关工具窗口关闭时，支持工具是否应停止容器。值为 `none`、`stopContainer`（图像或 Dockerfile 的默认值）和`stopCompose`（Docker Compose 的默认值）。
`init`???️	布尔值	默认为`false`. 跨协调器方式指示是否应使用tini init 进程来帮助处理僵尸进程。
`privileged`???️	布尔值	默认为`false`. 使容器在特权模式下运行的跨协调器方式 ( `--privileged`)。对于 Docker-in-Docker 之类的东西来说是必需的，但具有安全隐患，特别是直接在 Linux 上运行时。
`capAdd`???️	大批	默认为`[]`. 添加通常对容器禁用的功能的跨协调器方式。最常用于添加`ptrace`调试 C++、Go 和 Rust 等语言所需的功能。例如： `"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 Containers 功能 ID和相关选项的对象。可用的具体选项因功能而异，因此请参阅其文档以获取更多详细信息。例如： `"features": { "ghcr.io/devcontainers/features/github-cli": {} }`
`overrideFeatureInstallOrder`	大批	`installsAfter`默认情况下，功能将尝试根据每个功能中的属性自动设置它们的安装顺序。此属性允许您在需要时覆盖功能安装顺序。例如： `"overrideFeatureInstallorder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ]`
`customizations`???️	目的	产品特定属性，在支持工具中定义

场景特定属性

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

图像或 Dockerfile 特定属性

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

Docker Compose 特定属性

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

工具特定的属性

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

生命周期脚本

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

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

对于每个命令属性，如果该值是单个字符串，则它将在/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、存储和 GPU 要求可能很有用。这就是属性hostRequirements允许您执行的操作。云服务可以使用这些属性自动默认为可用的最佳计算选项，而在其他情况下，如果不满足要求，您将收到警告。

财产	类型	描述
`hostRequirements.cpus`???️	整数	指示所需的最小 CPU/虚拟 CPU/核心数。例如：`"hostRequirements": {"cpus": 2}`
`hostRequirements.memory`???️	细绳	指示最低内存要求的字符串，带有`tb`、`gb`、`mb`或`kb`后缀。例如，`"hostRequirements": {"memory": "4gb"}`
`hostRequirements.storage`???️	细绳	指示最低存储要求的字符串，带有`tb`、`gb`、`mb`或`kb`后缀。例如，`"hostRequirements": {"storage": "32gb"}`
`hostRequirements.gpu`???️	布尔值、字符串或对象	指示是否需要GPU。字符串“可选”表示 GPU 是可选的。对象值可用于配置更详细的需求。例如：`"hostRequirements": {"gpu": true}`

端口属性

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

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

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

"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`）。未设置的变量留空。例如，这会将变量设置为 Linux / macOS 上的本地主文件夹或 Windows 上的用户文件夹： `"remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" }` 未设置环境变量时的默认值可以使用`${localEnv:VARIABLE_NAME:default_value}`. ⚠️ 对于云服务，主机位于云端而不是本地计算机。
`${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}`	任何	源自一组容器标签的标识符，这些标签唯一地标识 Docker 主机上的 Dev Containers 。它允许功能引用一个标识符，该标识符对于它们安装到的 Dev Containers 来说是唯一的，并且在重建过程中保持稳定。 devcontainer.json 中支持它的属性有：`name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, ,`remoteUser`和`customizations`。