为 GitHub Codespaces 设置 Python 项目

通过创建自定义开发容器配置，在 GitHub Codespaces 中使用 Python 项目入门。

本文内容

简介

本指南介绍如何使用 Visual Studio Code Web 客户端在 GitHub Codespaces 中设置示例 Python 项目。它将逐步指导你完成在 Codespace 中打开项目以及添加和修改预定义开发容器配置的过程。

完成本教程后，你将能够使用 VS Code Web 客户端或 VS Code 桌面应用程序将开发容器配置添加到自己的存储库。

有关开发容器的更多信息，请参阅“开发容器简介”。

步骤 1：在 Codespace 中打开项目

  1. 登录 GitHub.com（如果你尚未登录）。

  2. 转到 https://github.com/microsoft/vscode-remote-try-python。

  3. 单击使用此模板，然后单击在代码空间中打开。

    Screenshot of the "Use this template" button and the dropdown menu expanded to show the "Open in a codespace" option.

创建代码空间时，你的项目将创建在你专用的远程虚拟机上。默认情况下，你的代码空间容器包含多种语言和运行时，包括 Python。它还包含一组通用工具，如 git、wget、rsync、openssh 和 nano。

你可以通过调整 vCPU 和 RAM 的数量、添加 dotfile 来个性化你的环境，或修改已安装的工具和脚本来自定义你的代码空间。有关更多信息，请参阅“自定义你的代码空间”。

GitHub Codespaces 使用名为 devcontainer.json 的文件来配置你在代码空间中工作时使用的开发容器。每个存储库可以包含一个或多个 devcontainer.json 文件，以便为你提供在代码空间中处理代码所需的开发环境。

启动时，GitHub Codespaces 使用 devcontainer.json 文件和构成开发容器配置的任何依赖文件来安装工具和运行时，并执行项目所需的其他设置任务。有关更多信息，请参阅“开发容器简介”。

步骤 2：添加开发容器配置

GitHub Codespaces 的默认开发容器或“开发容器”附带最新 Python 版本、包管理器 (pip、Miniconda) 和其他预安装的通用工具。但是，我们建议你配置自己的开发容器，以包含你的项目所需的所有工具和脚本。这将确保存储库中所有 GitHub Codespaces 用户拥有完全可复制的环境。

要设置存储库以使用自定义开发容器，你需要创建一个或多个 devcontainer.json 文件。你可以在 Visual Studio Code 中从预定义的配置模板添加这些文件，也可以自己编写。有关开发容器配置的更多信息，请参阅“开发容器简介”。

  1. 访问 Visual Studio Code 命令面板 (Shift+Command+P / Ctrl+Shift+P)，然后开始键入“add dev”。单击Codespaces：添加开发容器配置文件。

    Screenshot of the Command Palette, with "add dev" entered and "Codespaces: Add Dev Container Configuration Files" listed.

  2. 单击创建新配置。

  3. 在此示例中，您用来创建代码空间的模板存储库已包含开发容器配置，因此会显示一条消息，告知您配置文件已存在。我们将覆盖现有配置文件，因此请单击继续。

  4. 单击显示所有定义。

    Screenshot of the "Add Dev Container Configuration Files" dropdown, showing various options, including "Show All Definitions."

  5. 开始键入python，然后在列表中单击Python 3。如果您的项目使用特定工具，则还有其他选项可用。例如，Python 3 和 PostgreSQL。

    Screenshot of the "Add Dev Container Configuration Files" dropdown, listing options for Python.

  6. 选择您希望用于项目的 Python 版本。在此情况下，选择标记为“（默认）”的版本。

    Screenshot of the "Add Dev Container Configuration Files" dropdown, listing various versions of Python 3.

  7. 显示了一系列其他功能。我们将安装 Coverage.py，这是一个适用于 Python 的代码覆盖率工具。要安装此工具，请键入py，选择Coverage.py (通过 pipx)，然后单击确定。

    Screenshot of the "Add Dev Container Configuration Files" dropdown, with "Coverage.py" selected.

  8. 显示了一条消息，告知您开发容器配置文件已存在。单击覆盖。

    创建了一个devcontainer.json文件，并在编辑器中将其打开。

您的自定义开发容器配置的详细信息

如果您查看 Visual Studio Code Explorer，您会看到已向项目的存储库根目录添加了一个.devcontainer目录，其中包含devcontainer.json文件。这是从该存储库创建的代码空间的主要配置文件。

devcontainer.json

您添加的devcontainer.json文件将包含name、image和features属性的值。还包括一些您可能觉得有用的其他属性，但已注释掉。

该文件将类似于以下内容，具体取决于您选择的映像

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
  "name": "Python 3",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/python:0-3.11-bullseye",
  "features": {
    "ghcr.io/devcontainers-contrib/features/coverage-py:2": {}
  }

  // Features to add to the dev container. More info: https://containers.dev/features.
  // "features": {},

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [],

  // Use 'postCreateCommand' to run commands after the container is created.
  // "postCreateCommand": "pip3 install --user -r requirements.txt",

  // Configure tool-specific properties.
  // "customizations": {},

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}
  • name：您可以根据需要为您的开发容器命名。已提供默认值。
  • image：容器注册表中的映像名称（DockerHub、GitHub 容器注册表或Azure 容器注册表），该映像将用于为代码空间创建开发容器。
  • 功能：一个或多个对象的列表，每个对象都引用一个可用的开发容器功能。功能是独立的、可共享的安装代码和开发容器配置单元。它们提供了一种简单的方法，可以向开发容器中添加更多工具、运行时或库功能。可以在 VS Code 中或 GitHub.com 上的 devcontainer.json 编辑器中添加功能。有关详细信息，请在“向 devcontainer.json 文件添加功能”中单击 Visual Studio Code 或 Web 浏览器 选项卡。
  • forwardPorts：此处列出的任何端口都将自动转发。有关详细信息，请参阅“在 Codespace 中转发端口”。
  • postCreateCommand：使用此属性可在创建 Codespace 后运行命令。可以将其格式化为字符串（如上所示）、数组或对象。有关详细信息，请参阅 Development Containers 网站上的开发容器规范。
  • customizations：此属性允许在将特定工具或服务用于在 Codespace 中工作时对其进行自定义。例如，可以为 VS Code 配置特定设置和扩展。有关详细信息，请参阅 Development Containers 网站上的“支持的工具和服务”。
  • remoteUser：默认情况下，你以 vscode 用户身份运行，但可以选择将其设置为 root。

有关可用属性的完整列表，请参阅 Development Containers 网站上的开发容器规范。

其他开发容器配置文件

如果你熟悉 Docker，则可能希望使用 Dockerfile 或 Docker Compose 来配置 Codespace 环境，除了 devcontainer.json 文件之外。可以通过将 Dockerfile 或 docker-compose.yml 文件与 devcontainer.json 文件一起添加来执行此操作。有关详细信息，请参阅 Development Containers 网站上的“使用映像、Dockerfile 和 Docker Compose”。

步骤 3：修改 devcontainer.json 文件

添加了开发容器配置，并且基本了解了每个功能后，现在可以进行更改以进一步自定义环境。在此示例中，你将添加以下属性：

  • 安装应用程序所需的包。
  • 在此代码空间中安装 VS Code 扩展。

  1. 在 devcontainer.json 文件中，在 features 属性后添加一个逗号，并删除有关功能的两行注释。

    JSON
    "features": {
  "ghcr.io/devcontainers-contrib/features/coverage-py:2": {}
},

// Features to add to the dev container. More info: https://containers.dev/features.
// "features": {},

  2. 取消对 postCreateCommand 属性的注释。

    JSONC
    // Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "pip3 install --user -r requirements.txt",

  3. 取消对 customizations 属性的注释，并按如下方式对其进行编辑以安装“Code Spell Checker”VS Code 扩展。

    JSONC
    // Configure tool-specific properties.
"customizations": {
  // Configure properties specific to VS Code.
  "vscode": {
    // Add the IDs of extensions you want installed when the container is created.
    "extensions": [
      "streetsidesoftware.code-spell-checker"
    ]
  }
}

    devcontainer.json 文件现在应类似于以下内容，具体取决于你选择的映像

    // For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
  "name": "Python 3",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/python:0-3.11-bullseye",
  "features": {
    "ghcr.io/devcontainers-contrib/features/coverage-py:2": {}
  },

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [],

  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "pip3 install --user -r requirements.txt",

  // Configure tool-specific properties.
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      // Add the IDs of extensions you want installed when the container is created.
      "extensions": [
        "streetsidesoftware.code-spell-checker"
      ]
    }
  }

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}

  4. 保存更改。

  5. 访问 VS Code 命令面板（Shift+Command+P / Ctrl+Shift+P），然后开始键入“重建”。单击代码空间：重建容器。

    Screenshot of the Command Palette with "rebuild" entered in the text box and the "Codespace: Rebuild Container" option highlighted in the dropdown.

    提示：你可能偶尔需要执行完全重建以清除缓存并使用新映像重建容器。有关详细信息，请参阅“在代码空间中重建容器”。

    在代码空间内重建可确保在将更改提交到存储库之前，更改按预期工作。如果确实导致失败，你将被置于具有恢复容器的代码空间中，你可以从中重建以继续调整容器。

    在开发容器重建后，并且代码空间再次可用后，将运行 postCreateCommand，安装 requirements.txt 文件中列出的包，并且“Code Spell Checker”扩展将可供使用。

步骤 4：运行应用程序

在上一部分中，你使用 postCreateCommand 为 Flask Web 框架安装了一个包。你现在可以使用它来运行 Web 应用程序。

  1. 在代码空间的终端中，输入python -m flask run。

    Screenshot of the Terminal tab with the command "python -m flask run" entered, and output including "Running on http://127.0.0.1:5000."

  2. 当项目启动时，你应该会看到 VS Code 右下角的“提示”通知消息，告诉你应用程序在已转发的端口上可用。要查看正在运行的应用程序，请单击在浏览器中打开。

    Screenshot of the port forwarding message, reading "Your application running on port 5000 is available." The "Open in Browser" button is also shown.

步骤 5：提交你的更改

当你对代码空间进行了更改，无论是新代码还是配置更改，你都会想要提交你的更改。将配置更改提交到你的存储库可确保从该存储库创建代码空间的任何人都具有相同的配置。你所做的任何自定义，例如添加 VS Code 扩展，都将对所有用户可用。

对于本教程，你从模板存储库创建了代码空间，因此代码空间中的代码尚未存储在存储库中。你可以通过将当前分支发布到 GitHub.com 来创建存储库。

有关信息，请参阅“在你的代码空间中使用源代码控制”。

后续步骤

你现在应该能够向你自己的 Python 项目添加自定义开发容器配置。

以下是一些适用于更高级场景的其他资源。