开发容器简介

关于 dev 容器

开发容器（或 dev 容器）是专门配置的 Docker 容器，用于提供功能齐全的开发环境。在 Codespace 中工作时，您始终使用虚拟机上的 dev 容器。

您可以为存储库配置开发容器，以便为该存储库创建的 Codespaces 为您提供定制的开发环境，其中包含您在特定项目上工作所需的所有工具和运行时。如果您未在存储库中定义配置，则 GitHub Codespaces 将使用默认配置，其中包含团队可能需要用于与项目进行开发的许多常用工具。有关更多信息，请参阅“使用默认开发容器配置”。

开发容器的配置文件包含在存储库中的 .devcontainer 目录中。您可以使用 Visual Studio Code 为您添加配置文件。您可以从各种项目类型的预定义配置中进行选择。您可以直接使用这些配置，也可以编辑这些配置以优化它们生成的开发环境。有关更多信息，请参阅“使用预定义的开发容器配置”。

或者，您可以添加自己的自定义配置文件。有关更多信息，请参阅“创建自定义开发容器配置”。

您可以为存储库定义单个开发容器配置，为不同分支定义不同的配置，或定义多个配置。当有多个配置可用时，用户可以在创建 Codespace 时选择他们喜欢的配置。这对于包含不同编程语言的源代码或不同项目的大型存储库特别有用。您可以创建多种配置，让不同的团队在适合其工作的 Codespace 中工作。

当您从模板创建 Codespace 时，您的工作区中可能包含一个或多个开发容器配置文件。要进一步配置您的环境，您可以从这些文件中添加或删除设置，然后重建容器以将更改应用于您正在使用的 Codespace。如果您将 Codespace 发布到 GitHub 上的存储库，则从该存储库创建的任何 Codespace 都将共享您定义的配置。有关更多信息，请参阅“将配置更改应用于 Codespace”和“从模板创建 Codespace”。

devcontainer.json

开发容器配置中的主要文件是 `devcontainer.json` 文件。您可以使用此文件来确定为您的存储库创建的代码空间的环境。此文件的内容定义了一个开发容器，其中可以包含框架、工具、扩展和端口转发。`devcontainer.json` 文件通常包含对 Dockerfile 的引用，该文件通常位于 `devcontainer.json` 文件旁边。

如果您从没有 `devcontainer.json` 文件的存储库创建代码空间，或者从 GitHub 的空白模板开始，则使用默认的开发容器配置。有关更多信息，请参阅“使用默认开发容器配置”。

`devcontainer.json` 文件通常位于存储库的 `.devcontainer` 目录中。或者，您可以将其直接放在存储库的根目录中，在这种情况下，文件名必须以句点开头：`.devcontainer.json`。

如果您希望在存储库中选择开发容器配置，则 `devcontainer/devcontainer.json`（或 `.devcontainer.json`）文件的任何替代方案必须位于路径 `devcontainer/SUBDIRECTORY/devcontainer.json` 的自己的子目录中。例如，您可以选择两种配置

.devcontainer/database-dev/devcontainer.json
.devcontainer/gui-dev/devcontainer.json

当您的存储库中有多个 `devcontainer.json` 文件时，每个代码空间都只从其中一个配置创建。设置不能在 `devcontainer.json` 文件之间导入或继承。如果自定义子目录中的 `devcontainer.json` 文件具有依赖文件，例如 Dockerfile 或由 `devcontainer.json` 文件中的命令运行的脚本，建议您将这些文件放在同一个子目录中。

有关在创建代码空间时如何选择您首选的开发容器配置的信息，请参阅“为存储库创建代码空间”。

有关您可以在 `devcontainer.json` 文件中设置的设置和属性的信息，请参阅开发容器网站上的规范。

如何使用 devcontainer.json

将 devcontainer.json 文件视为提供“定制”，而不是“个性化”会很有帮助。您应该只包含代码库中每个人都需要作为开发环境标准元素的内容，而不是个人偏好。诸如 linter 之类的东西适合标准化，并要求每个人都安装，因此适合包含在您的 devcontainer.json 文件中。诸如用户界面装饰器或主题之类的东西是个人选择，不应放在 devcontainer.json 文件中。

您可以使用点文件和设置同步来个性化您的代码空间。有关更多信息，请参阅“个性化您的 GitHub 代码空间”。

Dockerfile

您可以将 Dockerfile 添加到您的开发容器配置中。

Dockerfile 是一个文本文件，其中包含创建 Docker 容器镜像所需的指令。每次有人使用引用此 Dockerfile 的 devcontainer.json 文件创建代码空间时，都会使用此镜像生成开发容器。Dockerfile 中的指令通常从引用将要创建的新镜像所基于的父镜像开始。之后是图像创建过程中运行的命令，例如安装软件包。

开发容器的 Dockerfile 通常位于 .devcontainer 文件夹中，与它所引用的 devcontainer.json 文件并排。

注意：作为使用 Dockerfile 的替代方法，您可以使用 devcontainer.json 文件中的 image 属性直接引用您要使用的现有镜像。您在此处指定的镜像必须符合已设置的任何组织镜像策略。有关更多信息，请参阅“限制代码空间的基镜像”。如果未找到 Dockerfile 或镜像，则使用默认容器镜像。有关更多信息，请参阅“使用默认开发容器配置”。

简单的 Dockerfile 示例

以下示例使用四个指令

ARG 定义构建时变量。

FROM 指定生成的 Docker 镜像将基于的父镜像。如果已配置基镜像策略，只允许使用某些镜像，则指定的镜像必须与策略中的镜像引用之一匹配。如果不匹配，则此存储库的代码空间将在恢复模式下创建。有关更多信息，请参阅“限制代码空间的基镜像”。

COPY 从存储库复制文件并将其添加到代码空间的文件系统中。

RUN 更新软件包列表并运行脚本。您也可以使用 RUN 指令来安装软件，如注释掉的指令所示。要运行多个命令，请使用 && 将命令组合到单个 RUN 语句中。

Dockerfile

ARG VARIANT="16"
FROM mcr.microsoft.com/devcontainers/javascript-node:1-${VARIANT}

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends bundler

# [Optional] Uncomment if you want to install an additional version
#  of node using nvm
# ARG EXTRA_NODE_VERSION=18
# RUN su node -c "source /usr/local/share/nvm/nvm.sh \
#    && nvm install ${EXTRA_NODE_VERSION}"

COPY ./script-in-your-repo.sh /tmp/scripts/script-in-codespace.sh
RUN apt-get update && bash /tmp/scripts/script-in-codespace.sh

ARG VARIANT="16"
FROM mcr.microsoft.com/devcontainers/javascript-node:1-${VARIANT}

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends bundler

# [Optional] Uncomment if you want to install an additional version
#  of node using nvm
# ARG EXTRA_NODE_VERSION=18
# RUN su node -c "source /usr/local/share/nvm/nvm.sh \
#    && nvm install ${EXTRA_NODE_VERSION}"

COPY ./script-in-your-repo.sh /tmp/scripts/script-in-codespace.sh
RUN apt-get update && bash /tmp/scripts/script-in-codespace.sh

注意：在上面的示例中，复制到代码空间的脚本 (script-in-your-repo.sh) 必须存在于您的存储库中。

有关 Dockerfile 指令的更多信息，请参阅 Docker 文档中的“Dockerfile 参考”。

使用 Dockerfile

要将 Dockerfile 用作开发容器配置的一部分，请使用 dockerfile 属性在您的 devcontainer.json 文件中引用它。

JSONC

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

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

如果您想在开发容器中使用现有的容器编排，则可以使用各种选项。有关更多信息，请参阅开发容器网站上的“编排选项”部分的规范。

使用默认开发容器配置

如果您没有将开发容器配置添加到您的存储库，或者您的配置没有指定要使用的基本映像，那么 GitHub 将从默认的 Linux 映像创建容器。此 Linux 映像包含许多流行语言（如 Python、Node、PHP、Java、Go、C++、Ruby 和 .NET Core/C#）的运行时版本。使用这些语言的最新版本或 LTS 版本。还有一些工具可以支持数据科学和机器学习，例如 JupyterLab 和 Conda。默认的开发容器映像还包含其他开发人员工具和实用程序，如 Git、GitHub CLI、yarn、openssh 和 vim。要查看包含的所有语言、运行时和工具，请在代码空间终端中使用 devcontainer-info content-url 命令，然后按照命令输出的 URL 操作。

有关默认 Linux 映像中包含的内容的信息，请参阅 devcontainers/images 存储库。

如果您正在处理一个使用 GitHub Codespaces 提供的语言和工具的小型项目，那么默认配置是一个不错的选择。

注意：GitHub 不对从默认开发容器映像构建的容器的存储收费。有关代码空间存储计费的更多信息，请参阅“关于 GitHub Codespaces 的计费”。有关如何检查代码空间是否是从默认开发容器映像构建的信息，请参阅“充分利用您的包含使用量”。

使用预定义的开发容器配置

如果您在 Visual Studio Code 或 Web 浏览器中使用 Codespaces，则可以通过从预定义配置列表中选择来为您的存储库创建开发容器配置。这些配置为特定项目类型提供常见的设置，可以帮助您快速开始使用已经具有适当容器选项、Visual Studio Code 设置和应安装的 Visual Studio Code 扩展的配置。

如果您需要额外的扩展性，使用预定义配置是一个好主意。您也可以从预定义配置开始，并根据需要修改它以适应您的项目。有关预定义开发容器定义的更多信息，请参阅 devcontainers/images 存储库。

您可以在 Codespace 中工作时或在本地工作区中工作时添加预定义的开发容器配置。要在本地工作时（未连接到 Codespace）在 VS Code 中执行此操作，您必须安装并启用“开发容器”扩展。有关此扩展的更多信息，请参阅 VS Code 市场。以下步骤描述了在使用 Codespace 时执行此操作的过程。在未连接到 Codespace 时，VS Code 中的步骤非常相似。

访问 Visual Studio Code 命令面板（Shift+Command+P / Ctrl+Shift+P），然后开始输入“add dev”。单击 **Codespaces: 添加开发容器配置文件**。
单击 **创建新的配置**。
单击 **显示所有定义**。
单击您要使用的定义。
按照提示自定义您的定义。
单击 **确定**。
如果您在 Codespace 中工作，请通过单击窗口右下角弹出的 **立即重建** 来应用您的更改。有关重建容器的更多信息，请参阅“将配置更改应用于 Codespace”。

向您的 `devcontainer.json` 文件添加更多功能

功能是安装代码和开发容器配置的独立单元，旨在跨广泛的基础容器映像工作。您可以使用功能快速将工具、运行时或库添加到您的 Codespace 映像。有关更多信息，请参阅开发容器网站上的可用功能和功能规范。

您可以从 VS Code 或 GitHub.com 上的存储库中向 devcontainer.json 文件添加功能。有关更多信息，请参阅“向 devcontainer.json 文件添加功能”。

创建自定义开发容器配置

如果预定义的配置都不满足您的需求，您可以通过编写自己的 devcontainer.json 文件来创建自定义配置。

如果您要添加一个将由从您的存储库创建代码空间的每个人使用的单个 devcontainer.json 文件，请在存储库根目录下的 .devcontainer 目录中创建该文件。
如果您想为用户提供配置选择，您可以创建多个自定义 devcontainer.json 文件，每个文件都位于 .devcontainer 目录的单独子目录中。
注意:
- 您不能将 devcontainer.json 文件放在比 .devcontainer 低一级以上的目录中。例如，.devcontainer/teamA/devcontainer.json 中的文件将起作用，但 .devcontainer/teamA/testing/devcontainer.json 不会。
- 当用户从模板存储库中的“使用此模板”按钮创建代码空间时，他们将无法在配置之间进行选择。代码空间将根据 .devcontainer/devcontainer.json 中定义的默认配置或存储库根目录下的 .devcontainer.json 中定义的默认配置构建。有关更多信息，请参阅“为 GitHub Codespaces 设置模板存储库”。
如果在存储库中找到多个 devcontainer.json 文件，它们将在代码空间创建选项页面上的“开发容器配置”下拉菜单中列出。有关更多信息，请参阅“为存储库创建代码空间”。

添加 `devcontainer.json` 文件

如果您在存储库中还没有 devcontainer.json 文件，您可以从 GitHub.com 快速添加一个。

导航到您的仓库并点击 ** 代码** 下拉菜单。
在 **Codespaces** 选项卡中，点击省略号 (**...**)，然后选择 **配置开发容器**。

一个新的 .devcontainer/devcontainer.json 文件将在编辑器中打开。该文件将包含一些初始属性，包括一个 features 对象，您可以向其中添加新的工具、库或运行时。有关更多信息，请参阅 "向 devcontainer.json 文件添加功能"。

如果您的仓库已经包含一个或多个 devcontainer.json 文件，那么点击 **配置开发容器** 将打开现有的 devcontainer.json 文件，该文件具有根据规范在开发容器网站上具有最高优先级。

创建 codespace 时的默认配置选择

如果 .devcontainer/devcontainer.json 或 .devcontainer.json 存在，它将是您创建 codespace 时可用配置文件列表中的默认选择。如果这两个文件都不存在，则默认开发容器配置将被默认选中。

在以下屏幕截图中，仓库不包含 .devcontainer/devcontainer.json 或 .devcontainer.json 文件，因此选择了默认开发容器配置。但是，在 .devcontainer 目录的子目录中定义了两个备用配置文件，因此它们被列为选项。

Screenshot of the "Dev container configuration" dropdown with the default configuration choice selected.

编辑 devcontainer.json 文件

您可以在 devcontainer.json 文件中添加和编辑支持的配置键，以指定 codespace 环境的各个方面，例如将安装哪些 VS Code 扩展。有关您可以在 devcontainer.json 文件中设置的设置和属性的信息，请参阅开发容器网站上的规范。

devcontainer.json 文件使用 JSONC（带注释的 JSON）格式编写。这允许您在配置文件中包含注释。有关更多信息，请参阅 VS Code 文档中的“使用 VS Code 编辑 JSON”。

注意：如果您使用 linter 验证 devcontainer.json 文件，请确保将其设置为 JSONC 而不是 JSON，否则注释将被报告为错误。

VS Code 的界面设置

您可以配置 VS Code 的界面设置，它有三个范围：用户、远程 [Codespaces] 和工作区。您可以在 VS Code 设置编辑器中查看这些范围。

要显示设置编辑器，请使用键盘快捷键 Command+,（Mac）/ Ctrl+,（Linux/Windows）。

Screenshot of the "Settings" editor with the tabs for the three scopes highlighted with an orange outline.

如果某个设置在多个范围内定义，则工作区设置优先，然后是远程 [Codespaces]，最后是用户。

您可以在两个地方定义 VS Code 的默认界面设置。

在您的存储库中的 .vscode/settings.json 文件中定义的界面设置将作为工作区范围的设置应用于 codespace。
在 devcontainer.json 文件的 settings 键中定义的界面设置将作为远程 [Codespaces] 范围的设置应用于 codespace。

将配置更改应用于 codespace

配置更改将在您下次创建 codespace 时应用。但是，您可以通过重建容器将更改应用于现有 codespace。您可以在 VS Code Web 客户端或桌面应用程序的 codespace 中执行此操作，也可以使用 GitHub CLI。

注意：当您在 codespace 中重建容器时，您在 /workspaces 目录之外所做的更改将被清除。您在 /workspaces 目录内所做的更改（包括您创建 codespace 的存储库或模板的克隆）将在重建后保留。有关更多信息，请参阅“深入了解 GitHub Codespaces”。

在 VS Code 网页客户端或桌面应用程序中重建开发容器

访问 VS Code 命令面板（Shift+Command+P / Ctrl+Shift+P），然后开始输入“rebuild”。点击 **Codespaces: 重建容器**。

提示： 您可能偶尔需要执行完全重建以清除缓存并使用新的镜像重建容器。有关更多信息，请参阅“在 Codespace 中重建容器”。
如果开发容器配置的更改导致容器错误，您的 Codespace 将在恢复模式下运行，您将看到错误消息。
- 要通过查看创建日志诊断错误，请点击 **查看创建日志**。
- 要修复日志中识别的错误，请更新您的 devcontainer.json 文件。
- 要应用更改，请重建您的容器。