深入了解 GitHub Codespaces

了解 GitHub Codespaces 的工作原理。

本文中

GitHub Codespaces 是一种即时、基于云的开发环境，它使用容器为您提供常见的语言、工具和实用程序以进行开发。GitHub Codespaces 还可以进行配置，允许您为您的项目创建自定义开发环境。通过为您的项目配置自定义开发环境，您可以为您的项目的所有用户提供可重复的 Codespace 配置。

创建您的 Codespace

有多个入口点可以创建 Codespace。

  • 从 GitHub 模板或 GitHub.com 上的任何模板存储库开始一个新项目
  • 从您的存储库中的分支开始一项新功能工作
  • 从一个开放的拉取请求探索正在进行的工作
  • 从存储库历史记录中的一个提交来调查特定时间点的错误

您可以在 GitHub.com、Visual Studio Code 中或使用 GitHub CLI 创建 Codespace。

如果您需要测试某些内容，您的 Codespace 可以是临时的，或者您可以返回到同一个 Codespace 继续进行长期功能工作。

有关更多信息，请参阅“为存储库创建 Codespace”、“从模板创建 Codespace”和“打开现有的 Codespace”。

注意：您可以为每个存储库甚至每个分支创建多个 Codespace。但是，您可以创建的 Codespace 数量以及您可以同时运行的 Codespace 数量都有限制。如果您达到 Codespace 的最大数量并尝试创建另一个 Codespace，则会显示一条消息，告诉您必须删除现有的 Codespace 才能创建新的 Codespace。

Codespace 创建过程

当您创建 Codespace 时，在 Codespace 可供您使用之前，后台会发生各种步骤。

步骤 1：为您的 Codespace 分配虚拟机和存储

当您创建 Codespace 时，将使用虚拟机 (VM) 主机映像的稳定版或测试版创建一个虚拟机 (VM)。有关更多信息，请参阅“选择稳定版或测试版主机映像”。主机映像定义了用于虚拟机的 Linux 版本。虚拟机是专用的，并且对您是私有的。拥有专用的虚拟机可确保您可以使用该机器上的所有计算资源。如有必要，这也允许您完全 root 访问您的容器。

然后对您的存储库（如果您要从模板创建 Codespace，则对模板存储库）进行浅层克隆。这将克隆到虚拟机的 /workspaces 目录中，然后挂载到开发容器中。有关更多信息，请参阅下面的“关于 Codespace 的目录结构”。

步骤 2：创建开发容器

GitHub Codespaces 使用 Docker 容器作为开发环境。此容器基于您可以在 devcontainer.json 文件中定义的配置（还可以选择 Dockerfile）创建。如果您从 GitHub 的空白模板或没有 devcontainer.json 文件的存储库创建 Codespace，GitHub Codespaces 将使用默认映像，其中提供了许多语言和运行时。有关更多信息，请参阅“开发容器简介”。有关开发容器默认映像包含内容的详细信息，请参阅 devcontainers/images 存储库。

注意：如果您想在 Codespace 中使用 Git 钩子并在 git 模板目录 中将任何内容应用到 Codespace，则必须在创建容器后在步骤 4 中设置钩子。

由于在创建容器之前将存储库克隆到主机 VM 上，因此除非您在步骤 4 中使用 postCreateCommand 在 devcontainer.json 配置文件中设置钩子，否则 git 模板目录 中的任何内容都不会应用到 Codespace。有关更多信息，请参阅“步骤 4：创建后设置”。

步骤 3：连接到 Codespace

创建容器并运行任何其他初始化后，您将连接到 Codespace。您可以使用以下方式连接到它

步骤 4：创建后设置

连接到 Codespace 后，您的自动化设置可能会继续根据 devcontainer.json 文件中指定的配置进行构建。您可能会看到 postCreateCommand 和 postAttachCommand 运行。

如果您想在代码空间中使用 Git 钩子，请使用 devcontainer.json 生命周期脚本（例如 postCreateCommand）设置钩子。有关生命周期脚本的信息，请参阅 Development Containers 网站上的 dev 容器规范。

如果您有用于 GitHub Codespaces 的公共点文件存储库，则可以启用它以与新的代码空间一起使用。启用后，您的点文件将克隆到容器中，并且将调用安装脚本。有关更多信息，请参阅“为您的帐户个性化 GitHub Codespaces”。

最后，如果您从存储库创建了代码空间，则存储库的整个历史记录将通过完整克隆进行复制。如果您从模板创建了代码空间，则不会保留模板存储库的完整历史记录；相反，除非您使用空白模板，否则您将从模板存储库的内容开始进行初始提交。

在创建后设置期间，您仍然可以使用集成终端并编辑文件，但请注意避免您的工作与正在运行的命令之间的任何竞争条件。

Codespaces 生命周期

在您的代码空间中保存文件

根据您使用的编辑器，以正常方式保存对文件的更改。

如果您在 Visual Studio Code 中处理代码空间，则可以启用 自动保存 以确保始终保存您的更改。

关闭或停止您的代码空间

在您使用时，您的代码空间将保持运行，但在一段时间不活动后将超时。编辑器和终端输出中的文件更改被视为活动，因此如果终端输出持续进行，您的代码空间将不会超时。默认不活动超时时间为 30 分钟。您可以为创建的代码空间定义您的个人超时设置，但组织超时策略可能会覆盖此设置。有关更多信息，请参阅“为 GitHub Codespaces 设置您的超时时间”。

如果代码空间超时，它将停止运行，但您可以从浏览器选项卡（如果您在浏览器中使用代码空间）、VS Code 中或 https://github.com/codespaces 中的代码空间列表中重新启动它。

要停止您的代码空间，您可以

如果你在不运行停止命令的情况下退出 codespace（例如，通过关闭浏览器标签），或者如果你让 codespace 在没有交互的情况下运行，codespace 及其正在运行的进程将在非活动超时期间继续运行。

关闭或停止 codespace 时，所有未提交的更改都将保留，直到你再次连接到 codespace。

运行你的应用程序

端口转发让你可以访问在 codespace 中运行的 TCP 端口。例如，如果你在 codespace 中的端口 4000 上运行 Web 应用程序，你可以自动转发该端口，以便从浏览器访问该应用程序。

端口转发确定哪些端口可以从远程计算机访问。即使你不转发端口，该端口仍然可以被 codespace 本身内部运行的其他进程访问。

Diagram showing connections, over the internet, between a code editor or a browser on your device and a codespace on the cloud.

当在 GitHub Codespaces 中运行的应用程序向控制台输出端口时，GitHub Codespaces 会检测 localhost URL 模式并自动转发端口。你可以单击终端中的 URL，或单击 VS Code 右下角弹出的“提示”通知消息中的链接，在浏览器中打开端口。默认情况下，GitHub Codespaces 使用 HTTP 转发端口。有关端口转发的详细信息，请参阅“在你的 codespace 中转发端口”。

虽然端口可以自动转发，但它们不会公开访问互联网。默认情况下，所有端口都是私有的，但你可以手动让端口对你的组织或公众可用，然后通过 URL 共享访问权限。有关详细信息，请参阅“在你的 codespace 中转发端口”。

当你首次进入代码空间时运行应用程序可以快速进行内部开发循环。当你编辑时，你的更改会自动保存并在你的转发端口上提供。要查看更改，请返回浏览器中的正在运行的应用程序选项卡并刷新它。

提交并推送你的更改

Git 默认安装在你的代码空间中，因此你可以依赖现有的 Git 工作流。你可以在代码空间中通过终端或使用 VS Code 或 JetBrains 的源代码控制功能来使用 Git。

如果你正在使用现有的存储库，你可以从存储库中的任何分支、提交或拉取请求创建代码空间，或者你可以在活动代码空间中切换到新的或现有的分支。由于 GitHub Codespaces 被设计为临时性的，因此你可以将其用作隔离环境来进行实验、检查队友的拉取请求或修复合并冲突。

如果你仅对存储库具有读取访问权限，那么只要你可以 fork 它，你就可以为存储库创建一个代码空间。当你从代码空间提交或推送新分支时，GitHub Codespaces 会自动为你创建存储库的分支，或者如果你已经为上游存储库创建了一个分支，则将代码空间链接到现有分支。

如果你在从模板创建的代码空间中工作，则默认安装 Git，但你需要将你的代码空间发布到远程存储库以保留你的工作并与他人共享。如果你从 GitHub 的空白模板开始，则首先需要将你的工作区初始化为 Git 存储库（例如通过输入 git init）才能开始在代码空间中使用源代码控制。

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

注意：你的代码空间中的提交将归因于在 https://github.com/settings/profile 中配置的名称和公共电子邮件。作为 GITHUB_TOKEN 包含在环境中的令牌范围限定为存储库，你的 GitHub 凭据将用于身份验证。

使用扩展或插件个性化你的代码空间

你可以在代码空间中添加插件和扩展，以分别个性化你在 JetBrains 和 VS Code 中的体验。

VS Code 扩展

如果您在 VS Code 桌面应用程序或 Web 客户端中处理您的 Codespaces，您可以从 Visual Studio Code Marketplace 中添加任何您需要的扩展。有关扩展如何在 GitHub Codespaces 中运行的信息，请参阅 VS Code 文档中的支持远程开发和 GitHub Codespaces。

如果您已经使用 VS Code，您可以使用设置同步在本地实例和您创建的任何 Codespaces 之间自动同步扩展、设置、主题和键盘快捷键。

JetBrains 插件

如果您在 JetBrains IDE 中处理您的 Codespaces，您可以从 JetBrains Marketplace 中添加插件。

  1. 单击JetBrains 客户端，然后单击首选项。

  2. 在首选项对话框中，单击主机上的插件以在远程运行的完整 JetBrains IDE 中安装插件，或单击插件以在本地客户端上安装插件，例如更改用户界面主题。

  3. 单击市场选项卡。

    Screenshot of the "Preferences" dialog, with the "Marketplace" tab displayed. The "Plugins On Host" option is highlighted with a dark orange outline.

  4. 单击所需插件旁边的安装。

关于 Codespace 的目录结构

当您创建 Codespace 时，您的存储库将克隆到 Codespace 中的 /workspaces 目录。这是一个持久目录，已装入容器。您在此目录中进行的任何更改，包括编辑、添加或删除文件，都将在您停止和启动 Codespace 以及在 Codespace 中重建容器时保留。

在 /workspaces 目录之外，您的 Codespace 包含一个 Linux 目录结构，该结构会根据用于构建您的 Codespace 的开发容器映像而有所不同。您可以在 /workspaces 目录之外添加文件或对文件进行更改：例如，您可以安装新程序，或者可以在 ~/.bashrc 等文件中设置 shell 配置。作为非 root 用户，您可能无法自动写入某些目录，但大多数映像允许使用 sudo 命令以 root 权限访问这些目录。

在 /workspaces 之外，除了 /tmp 目录外，Codespace 中的目录与容器的生命周期相关。这意味着您进行的任何更改都会在您停止和启动 Codespace 时保留，但不会在您重建容器时保留。有关 /tmp 目录的更多信息，请参阅“持久环境变量和临时文件”。

清除 /workspaces 之外的目录有助于确保重建的容器处于与新创建的 Codespace 中相同的状态。如果您要重建容器以将配置更改应用到您正在处理的 Codespace，您可以确信您所做的任何配置更改对使用相同配置创建新 Codespace 的用户都适用。有关更多信息，请参阅“开发容器简介”。

如果您希望对代码空间进行更改，以便在重建和跨不同代码空间时更加稳定，则有几种选择。

  • 要在从存储库创建的所有代码空间中安装程序和工具，可以在开发容器配置中使用生命周期命令属性（例如 postCreateCommand）来运行自定义安装命令，或者可以选择称为“功能”的预先编写的安装命令。有关详细信息，请参阅开发容器网站上的 开发容器规范 和“向 devcontainer.json 文件添加功能”。
  • 要在创建的每个代码空间中安装工具或自定义设置（例如配置 bash 配置文件），可以将 GitHub Codespaces 与点文件存储库链接。点文件存储库也会克隆到持久性 /workspaces 目录中。有关详细信息，请参阅“针对您的帐户个性化 GitHub Codespaces”。
  • 如果您希望在重建后保留特定文件，可以使用 devcontainer.json 文件在文件和 /workspaces 中的持久性目录之间创建符号链接。有关详细信息，请参阅“在代码空间中重建容器”。

延伸阅读