Configuring Codespaces for your project

You can use a devcontainer.json file to define a Codespaces environment for your repository.

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

注:Codespaces 目前是有限公测版,可能会有变动。 有关加入公测的更多信息,请参阅“关于 Codespaces”。

About dev containers

A development container, or dev container, is the environment that Codespaces uses to provide the tools and runtimes that your project needs for development. When working with a dev container in Codespaces you can either use the default configuration, use a pre-defined configuration, or create your own configuration. The option you choose is dependent on the tools, runtimes, dependencies, and workflows that a user might need to be successful with your project.

Codespaces allows for customization on a per-project and per-branch basis with a devcontainer.json file. This configuration file determines the environment of every new codespace anyone creates for your repository by defining a development container that can include frameworks, tools, extensions, and port forwarding. A Dockerfile can also be used alongside the devcontainer.json file in the .devcontainer folder to define everything required to create a container image.


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

You can use your devcontainer.json to set default settings for the entire codespace environment, including the editor, but you can also set editor-specific settings for individual workspaces in a codespace in a file named .vscode/settings.json.

For information about the settings and properties that you can set in a devcontainer.json, see devcontainer.json reference in the Visual Studio Code documentation.


A Dockerfile also lives in the .devcontainer folder.

You can add a Dockerfile to your project to define a container image and install software. In the Dockerfile, you can use FROM to specify the container image.


# ** [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

You can use the RUN instruction to install any software and && to join commands.

Reference your Dockerfile in your devcontainer.json file by using the dockerfile property.

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

For more information on using a Dockerfile in a dev container, see Create a development container in the Visual Studio Code documentation.

Using the default configuration

If you don't define a configuration in your repository, GitHub creates a codespace with a base Linux image. The base Linux image includes languages and runtimes like Python, Node.js, JavaScript, TypeScript, C++, Java, .NET, PHP, PowerShell, Go, Ruby, and Rust. It also includes other developer tools and utilities like git, GitHub CLI, yarn, openssh, and vim. To see all the languages, runtimes, and tools that are included use the devcontainer-info content-url command inside your codespace terminal and follow the url that the command outputs.

Alternatively, for more information about everything that is included in the base Linux image, see the latest file in the microsoft/vscode-dev-containers repository.

The default configuration is a good option if you're working on a small project that uses the languages and tools that Codespaces provides.

Using a predefined container configuration

Predefined container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, Visual Studio Code settings, and Visual Studio Code extensions that should be installed.

Using a predefined configuration is a great idea if you need some additional extensibility. You can also start with a predefined configuration and amend it as needed for your project's setup.

  1. Access the Command Palette (Shift + Command + P / Ctrl + Shift + P), then start typing "dev container". Select Codespaces: Add Development Container Configuration Files....

    "Codespaces: Add Development Container Configuration Files..." in the command palette

  2. Click the definition you want to use. List of predefined container definitions

  3. Follow the prompts to customize your definition.

  4. Click OK. OK button

  5. To apply the changes, in the bottom right corner of the screen, click Rebuild now. For more information about rebuilding your container, see "Applying changes to your configuration." "Codespaces: Rebuild Container" in the command palette

Creating a custom codespace configuration

If none of the predefined configurations meet your needs, you can create a custom configuration by adding a devcontainer.json file. 此文件可位于存储库的根目录或名为 .devtainer 的文件夹中。 如果文件位于仓库的根目录中,文件名必须以一个点开头:.devcontainer.json

In the file, you can use supported configuration keys to specify aspects of the codespace's environment, like which Visual Studio Code extensions will be installed.

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

You can define default editor settings for Visual Studio Code in two places.

  • Editor settings defined in .vscode/settings.json are applied as Workspace-scoped settings in the codespace.
  • Editor settings defined in the settings key in devcontainer.json are applied as Remote [Codespaces]-scoped settings in the codespace.

After updating the devcontainer.json file, you can rebuild the container for your codespace to apply the changes. For more information, see "Applying changes to your configuration."

Applying changes to your configuration

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

访问命令面板 (shift command P / shift control P),然后开始输入 "Codespaces: Rebuild Container"。 单击 Codespaces: Rebuild Container(代码空间:重建容器)

  1. 如果对代码空间的配置的更改导致容器错误,则代码空间将在恢复模式下运行,并且您将看到错误消息。 Fix the errors in the configuration. Error message about recovery mode
    • To diagnose the error by reviewing the creation logs, click View creation log.
    • To fix the errors identified in the logs, update your devcontainer.json file.
    • To apply the changes, rebuild your container.



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


或, 了解如何参与。