Introduction to dev containers

您可以使用 devcontainer.json 文件来定义仓库的 Codespaces 环境。

People with write permissions to a repository can create or edit the codespace configuration.

代码空间可用于使用 GitHub Team 或 GitHub Enterprise Cloud 的组织。 更多信息请参阅“GitHub 的产品”。

关于开发容器

开发容器是 Codespaces 用于提供项目开发所需的工具和运行时的环境。 If your project does not already have a dev container defined, Codespaces will use the default configuration, which contains many of the common tools that your team might need for development with your project. For more information, see "Using the default configuration."

If you want all users of your project to have a consistent environment that is tailored to your project, you can add a dev container to your repository. You can use a predefined configuration to select a common configuration for various project types with the option to further customize your project or you can create your own custom configuration. For more information, see "Using a predefined container configuration" and "Creating a custom codespace configuration." 您选择的选项取决于用户在项目中取得成功可能需要使用的工具、运行时、依赖项和工作流程。

Codespaces 允许使用 devcontainer.json 文件针对每个项目和每个分支进行自定义。 此配置文件通过定义可包括框架、工具、扩展和端口转发的开发容器,确定任何人为仓库创建的每个新代码空间的环境。 Dockerfile 还可与 .devcontainer 文件夹中的 devcontainer.json 文件一起使用,以定义创建容器映像所需的所有要素。

devcontainer.json

此文件可位于存储库的根目录或名为 .devtainer 的文件夹中。 如果文件位于仓库的根目录中,文件名必须以一个点开头:.devcontainer.json

您可以使用 devcontainer.json 为整个代码空间环境设置默认设置,包括编辑器,但您也可以在 .vscode/set.json 文件中设置代码空间中单个工作空间的编辑器特定设置。

有关在 devcontainer.json 中可以设置的设置和属性,请参阅 Visual Studio Code 文档中的 devcontainer.json 参考

Dockerfile

Dockerfile 也存在于 .devcontainer 文件夹中。

您可以将 Dockerfile 添加到项目中来定义容器映像和安装软件。 在 Dockerfile 中,您可以使用 FROM 来指定容器映像。

FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-14

# ** [Optional] Uncomment this section to install additional packages. **
# USER root
#
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>
#
# USER codespace

您可以使用 RUN 指令安装任何软件并使用 && 加入命令。

使用 dockerfile 属性,在您的 devcontainer.json 文件中引用 Dockerfile。

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

有关在开发容器中使用 Dockerfile 的更多信息,请参阅 Visual Studio Code 文档中的创建开发容器

使用默认配置

如果您没有在仓库中定义配置,GitHub 将创建一个具有基本 Linux 映像的代码空间。 基本 Linux 映像包括语言和运行时,例如 Python、Node.js、JavaScript、TypeScript、C++、Java、.NET、PHP、PowerShell、Go、Ruby 和 Rust。 它还包括其他开发工具和实用程序,例如 git、GitHub CLI、yarn、openssh 和 vim。 要查看包含的所有语言、运行时和工具,请在代码空间终端内使用 devcontainer-info content-url 命令,然后遵循命令输出的 url。

或者,要详细了解基本 Linux 映像中包含的所有内容,请参阅 microsoft/vscode-dev-containers 仓库中的最新文件。

如果您要处理使用 Codespaces 提供的语言和工具的小型项目,默认配置是个不错的选择。

使用预定义的容器配置

预定义容器定义包括特定项目类型的共同配置,可帮助您利用现有的配置快速开始使用,配置中已经有适当的容器选项、Visual Studio Code 设置和应该安装的 Visual Studio Code 扩展。

如果您需要一些额外的扩展性,使用预先定义的配置是一个好主意。 您也可以从预定义的配置开始,然后根据项目的设置对其进行修改。

  1. Access the VS Code Command Palette (Shift + Command + P / Ctrl + Shift + P), then start typing "dev container". 选择 Codespaces: Add Development Container Configuration Files...(Codespaces:添加开发容器配置文件...).

    "Codespaces: Add Development Container Configuration Files..." in the VS Code Command Palette

  2. 单击要使用的定义。 预定义容器定义列表

  3. 按照提示自定义您的定义。 For more information on the options to customize your definition, see "Adding additional features to your devcontainer.json file."

  4. 单击 OK(确定)确定按钮

  5. 要应用更改,请在屏幕右下角单击 Rebuild now(立即重建)。 有关重建容器的更多信息,请参阅“应用对配置的更改”。 "Codespaces: Rebuild Container" in the VS Code Command Palette

Adding additional features to your devcontainer.json file

Note: This feature is in beta and subject to change.

You can add features to your predefined container configuration to customize which tools are available and extend the functionality of your workspace without creating a custom codespace configuration. For example, you could use a predefined container configuration and add the GitHub CLI as well. You can make these additional features available for your project by adding the features to your devcontainer.json file when you set up your container configuration.

You can add some of the most common features by selecting them when configuring your predefined container. For more information on the available features, see the script library in the vscode-dev-containers repository.

The select additional features menu during container configuration.

You can also add or remove features outside of the Add Development Container Configuration Files workflow.

  1. Access the Command Palette (Shift + Command + P / Ctrl + Shift + P), then start typing "configure". Select Codespaces: Configure Devcontainer Features. The Configure Devcontainer Features command in the command palette
  2. Update your feature selections, then click OK. The select additional features menu during container configuration.
  3. 要应用更改,请在屏幕右下角单击 Rebuild now(立即重建)。 有关重建容器的更多信息,请参阅“应用对配置的更改”。 命令面板中的"Codespaces:重建容器"

创建自定义代码空间配置

如果任何预定义的配置都不能满足您的需要,您可以通过添加 devcontainer.json 文件来创建自定义配置。 此文件可位于存储库的根目录或名为 .devtainer 的文件夹中。 如果文件位于仓库的根目录中,文件名必须以一个点开头:.devcontainer.json

在该文件中,您可以使用支持的配置键来指定代码空间环境的各个方面,例如要安装哪些 Visual Studio Code 扩展。

配置 Visual Studio Code 的编辑器设置时,有三个可用的作用域:工作区远程 [Codespaces]用户。 如果在多个作用域中定义了设置,工作区设置优先级最高,远程 [Codespaces] 次之,最后是用户

您可以在两个地方定义 Visual Studio Code 的默认编辑器设置。

  • .vscode/settings.json 中定义的编辑器设置在代码空间中用作 Workspace 范围的设置。
  • devcontainer.jsonsettings 键中定义的编辑器设置在代码空间中用作 Remote [Codespaces] 范围的设置。

在更新 devcontainer.json 文件后,您可以重建代码空间的容器来应用更改。 更多信息请参阅“应用对配置的更改”。

应用对配置的更改

在仓库的 Codespaces 配置更改后,您可以通过重建代码空间的容器来将更改应用于现有代码空间。

  1. Access the VS Code Command Palette (Shift + Command + P/ Ctrl + Shift + P), then start typing "rebuild". 选择 Codespaces: Rebuild Container(代码空间:重建容器)

    重建容器选项

  2. 如果对代码空间的配置的更改导致容器错误,则代码空间将在恢复模式下运行,并且您将看到错误消息。 修复配置中的错误。 有关恢复模式的错误消息

    • 要通过查看创建日志来诊断错误,请单击 View creation log(查看创建日志)
    • 要修复日志中发现的错误,请更新您的 devcontainer.json 文件。
    • 要应用更改,请重建容器。

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。