深入了解 GitHub Codespaces

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

创建 Codespace

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

• 从 GitHub 模板或 GitHub 上的任何模板代码库启动新项目
• 从代码库中的分支进行新的功能工作
• 从打开的拉取请求浏览正在进行的工作
• 从代码库历史记录中的提交调查特定时间点的错误

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

根据您的需求，您的 Codespace 可以是临时的（用于测试），也可以是持久的（用于长期功能开发）。

更多信息，请参见“为代码库创建 Codespace”、“从模板创建 Codespace”和“打开现有 Codespace”。

Codespace 创建过程

创建 Codespace 时，在 Codespace 可供您使用之前，后台会执行多个步骤。

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

创建 Codespace 时，将使用虚拟机 (VM) 主机映像的稳定版或公开预览版创建一个虚拟机 (VM)。更多信息，请参见“选择稳定版或 Beta 版主机映像”。主机映像定义用于 VM 的 Linux 版本。此 VM 专属于您且对您是私有的。拥有专用 VM 可确保您可以使用该机器的整套计算资源。如有必要，这还允许您完全访问容器的 root 权限。

然后，将对您的代码库（如果您是从模板创建 Codespace，则为模板代码库）进行浅克隆。这将克隆到 VM 的/workspaces目录中，然后挂载到开发容器中。更多信息，请参见下面的“关于 Codespace 的目录结构”。

步骤 2：创建开发容器

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

步骤 3：连接到 Codespace

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

• 您的 Web 浏览器
• Visual Studio Code
• JetBrains IDE
• GitHub CLI

步骤 4：创建后设置

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

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

如果您有 GitHub Codespaces 的公共点文件代码库，您可以启用它以用于新的 Codespace。启用后，您的点文件将被克隆到容器中，并将调用安装脚本。更多信息，请参见“个性化您的帐户的 GitHub Codespaces”。

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

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

Codespaces 生命周期

在 Codespace 中保存文件

以正常方式保存对文件的更改，具体取决于您使用的编辑器。

如果您在 Visual Studio Code 中使用 Codespaces，您可以启用自动保存以确保始终保存您的更改。

关闭或停止 Codespace

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

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

要停止 Codespace，您可以：

• 在浏览器中：在https://github.com/codespaces处的 Codespace 列表中，单击要停止的 Codespace 右侧的省略号 (**...**)，然后单击**停止 Codespace**。
• 在 VS Code 中：打开 Visual Studio Code 命令面板 - 例如，通过按Ctrl+Shift+P（Windows/Linux）或Shift+Command+P（Mac）- 输入Codespaces: stop，然后按Enter。更多信息，请参见“在 GitHub Codespaces 中使用 Visual Studio Code 命令面板”。
• 在 JetBrains 客户端中，单击 GitHub Codespaces 工具窗口顶部的停止按钮。更多信息，请参见“停止和启动 Codespace”的“JetBrains IDE”选项卡。
• 在终端窗口中：使用 GitHub CLI 命令gh codespace stop。更多信息，请参见“使用 GitHub CLI 使用 GitHub Codespaces”。

如果您在不运行停止命令的情况下退出 Codespace（例如，通过关闭浏览器选项卡），或者如果您在没有交互的情况下让 Codespace 保持运行状态，则 Codespace 及其正在运行的进程将在不活动超时时间内继续运行。

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

运行您的应用程序

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

端口转发确定哪些端口可从远程计算机访问。即使您不转发端口，该端口仍然可供 Codespace 本身中运行的其他进程访问。

当在 GitHub Codespaces 中运行的应用程序将端口输出到控制台时，GitHub Codespaces 会检测本地主机 URL 模式并自动转发端口。您可以单击终端中的 URL 或 VS Code 右下角弹出的“提示”通知消息中的链接，以在浏览器中打开端口。默认情况下，GitHub Codespaces 使用 HTTP 转发端口。有关端口转发的更多信息，请参见“转发 Codespace 中的端口”。

虽然可以自动转发端口，但它们无法公开访问互联网。默认情况下，所有端口都是私有的，但您可以手动将端口提供给您的组织或公开，然后通过 URL 共享访问权限。更多信息，请参见“转发 Codespace 中的端口”。

在您首次进入 Codespace 时运行您的应用程序可以加快内部开发循环速度。编辑时，您的更改会自动保存并可用于您转发的端口。要查看更改，请返回浏览器中正在运行的应用程序选项卡并刷新它。

提交和推送更改

Git 在您的 Codespace 中默认安装，因此您可以依赖于您现有的 Git 工作流程。您可以通过终端或使用 VS Code 或 JetBrains 的源代码管理功能在 Codespace 中使用 Git。

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

如果您只有代码库的读取权限，那么只要您可以fork它，您就可以为该代码库创建代码空间。当您从代码空间进行提交或推送新分支时，GitHub Codespaces 会自动为您创建代码库的fork，或者如果您已经拥有上游代码库的现有fork，则会将代码空间链接到该fork。

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

更多信息，请参阅“在您的代码空间中使用源代码管理”。

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

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

VS Code 扩展

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

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

JetBrains 插件

如果您在 JetBrains IDE 中使用代码空间，您可以从 JetBrains 市场添加插件。

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

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

3. 点击市场选项卡。

   

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

关于代码空间的目录结构

创建代码空间时，您的代码库会被克隆到代码空间中的/workspaces目录。这是一个持久性目录，已安装到容器中。您在此目录中进行的任何更改（包括编辑、添加或删除文件）都会在您停止和启动代码空间以及在代码空间中重建容器时保留。

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

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

清除/workspaces外部的目录有助于确保重建的容器与新创建的代码空间中的状态相同。如果您要重建容器以将配置更改应用于您正在使用的代码空间，您可以确信您所做的任何配置更改对于使用相同配置创建新代码空间的用户来说都将具有相同的效果。更多信息，请参阅“开发容器简介”。

如果您想对代码空间进行更改，使其在重建和不同代码空间之间更稳定，您可以选择几种方法。

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

进一步阅读

• “为您的组织启用或禁用 GitHub Codespaces”
• “管理您组织中 GitHub Codespaces 的成本”
• “向您的代码库添加开发容器配置”
• “了解代码空间生命周期”