Step 1: 创建你的第一个 Codespace 并推送代码

欢迎来到课程《使用 GitHub Codespaces 和 Visual Studio Code 开发代码》! 👋

为什么要用 Codespace 来开发软件？ Codespace 是一个托管在云端的开发环境。你可以通过将配置文件提交到仓库中（这也叫 “配置即代码” 的方式）来配置开发环境，这样一来，保证了所有开发者都能在统一、可重复的环境中高效工作。

每一个 Codespace 都运行在 GitHub 提供的虚拟机上，由 Docker 容器托管。你可以根据项目所需资源选择不同类型的虚拟机。

GitHub 提供了一系列功能，帮助你的团队灵活定制 Codespace，以实现最佳的开发体验与性能表现。例如，你可以：

• 直接从仓库创建一个 Codespace
• 从 Codespace 中推送代码到仓库
• 使用 VS Code 进行开发
• 通过自定义镜像调整环境
• 管理你的 Codespace

要开始使用 GitHub Codespaces 进行开发，你可以基于模板创建一个 Codespace，也可以从仓库中的任意分支或commit启动。 当你从模板创建时，可以选择空白模板，或使用适合你当前开发任务的预设模板。

⌨️ 实操环节: 启动一个 Codespace

建议你在浏览器中新开一个标签页进行以下操作，方便一边动手实践一边阅读本教程。

1. 打开你的仓库主页。
2. 点击页面中间的绿色 Code 按钮。
3. 在弹出的窗口中，切换到 Codespaces 标签页，然后点击 Create codespace on main 按钮。

   等待大约 2 分钟，Codespace 会在后台自动启动。 提示：这是一个虚拟机启动的过程。

4. 确认 Codespace 是否成功运行。浏览器中会打开一个基于 Web 的 VS Code 编辑器，同时底部会显示终端窗口，如下图所示：

⌨️ 实操环节：从 Codespace 推送代码到仓库

1. 在 Codespace 中，打开 VS Code 左侧资源管理器，找到并选择 index.html 文件。
2. 将文件中的 h1 标签替换为以下内容：

   <h1>Hello from the codespace!</h1>
   

3. 保存文件。

   提示：VS Code 通常会自动保存文件。

4. 在 VS Code 的终端中输入以下命令提交更改：

   git commit -a -m "Adding hello from the codespace!"
   

5. 将更改推送回仓库：

   git push
   

6. 现在你的代码已经成功推送到 GitHub 仓库！
7. 回到仓库主页，打开 index.html 文件，确认修改是否已经更新到仓库中。
8. 等待大约 20 秒后刷新当前页面。GitHub Actions 会自动检测你的进度并跳转到下一步。

Step 2: 为你的 Codespace 添加自定义镜像!

干得漂亮! 🎉 你已经成功创建了第一个 Codespace，并通过 VS Code 推送了代码!

你可以为仓库配置一个开发容器，这样无论谁在该仓库中创建 Codespace，都会自动获得一个为项目量身定制的开发环境，其中包含所需的工具和运行时。

什么是开发容器? 开发容器（Development containers 或 dev containers） 说白了就是一个 Docker 容器，提供了项目所需的开发环境。 每当你在 Codespace 中工作时，实际上就是在一个虚拟机上的 dev container 中进行开发。

一个 dev container 的配置文件是一个 JSON 文件，它可以让你自定义运行 Codespace 所使用的基础镜像、VS Code 设置、端口转发规则、启动命令等多种参数。

接下来，我们来添加一个 devcontainer.json 文件，为 Codespace 指定镜像。

⌨️ 实操环节

1. 回到仓库的 Code 标签页，点击 Add file 下拉按钮，然后选择 Create new file。

2. 在文件名输入框中输入以下路径：

   .devcontainer/devcontainer.json
   

3. 在新建的 .devcontainer/devcontainer.json 文件中，粘贴以下内容：

   {
     // Name this configuration
     "name": "Codespace for Skills!",
     // Use the base codespace image
     "image": "mcr.microsoft.com/vscode/devcontainers/universal:latest",
   
     "remoteUser": "codespace",
     "overrideCommand": false
   }
   

4. 点击 Commit changes，并选择 Commit changes directly to the main branch。

5. 返回仓库的 Code 标签页，再次创建一个新的 Codespace。

6. 点击页面中央的绿色 Code 按钮。

7. 在弹出的窗口中切换到 Codespaces 标签页。

8. 点击 Create codespace on main 按钮，或点击标签页上的 + 号，为主分支创建一个新的 Codespace。（你会看到之前创建的 Codespace 也列在这里。）

   等待大约 2 分钟，Codespace 会自动启动。

9. 像之前一样，确认新的 Codespace 是否已成功运行。 此时使用的镜像是 GitHub Codespaces 提供的默认镜像，其中预装了 Python、Node.js、Docker 等常用运行时和工具。 完整列表可以查看这里: https://aka.ms/ghcs-default-image 。你可以使用自定义镜像，详细说明见：配置 codespace 镜像

10. 等待约 20 秒后刷新当前页面。GitHub Actions 会自动识别进度并进入下一步。

Step 3: 自定义你的codespace!

🎉 你成功创建了一个使用自定义镜像的 Codespace!

你还可以进一步定制你的 Codespace，例如安装 VS Code 插件、添加功能、设置host等，让开发环境完全符合你的工作习惯。

接下来，我们将修改 devcontainer.json 文件，为 Codespace 添加一些自定义配置。

⌨️ 实操环节：在 devcontainer.json 文件中添加自定义设置

1. 打开仓库中的 .devcontainer/devcontainer.json 文件。

2. 在文件最后一个 } 之前，加入以下内容：

    ,
    // 当容器创建时自动安装的 VS Code 插件
    "customizations": {
        "vscode": {
            "extensions": [
                "GitHub.copilot"
            ]
        },
        "codespaces": {
            "openFiles": [
                "codespace.md"
            ]
        }
    }
   

3. 点击 Commit changes，并选择 Commit changes directly to the main branch。

4. 回到仓库首页，再次创建一个新的 Codespace。

5. 点击页面中央的绿色 Code 按钮。

6. 在弹出的窗口中切换到 Codespaces 标签页。

7. 确认当前活跃的 Codespace 数量未达到上限（通常最多允许 2 个）。详情可参考 了解 Codespace 生命周期。

   提示：若想停止正在运行的 Codespace，可点击 ••• 按钮（位于 ●Active 旁边），然后选择 Stop codespace。

8. 点击 Create codespace on main 按钮创建新的 Codespace。

   等待约 2 分钟，Codespace 将自动启动。

9. 和之前一样，确认你的 Codespace 已成功运行。

10. 启动后，codespace.md 文件会自动在 VS Code 编辑器中打开。

11. GitHub Copilot 插件也会出现在 VS Code 的扩展列表中。

通过这一配置，我们让 Codespace 在启动时自动安装插件，并在启动后自动打开指定文件。

接下来，我们再让 Codespace 在创建时自动执行一段代码！

⌨️ 实操环节：让 Codespace 创建后自动执行代码

1. 编辑 .devcontainer/devcontainer.json 文件。
2. 在最后一个 } 之前加入以下内容：

    ,
    "postCreateCommand": "echo '# Writing code upon codespace creation!'  >> codespace.md"
   

3. 点击 Commit changes，并选择 Commit changes directly to the main branch。
4. 回到仓库首页，创建一个新的 Codespace。
5. 点击页面中央的绿色 Code 按钮。
6. 在弹出的窗口中切换到 Codespaces 标签页。
7. 点击 Create codespace on main 按钮。

   等待大约 2 分钟，Codespace 会自动启动。

8. 和之前一样，确认 Codespace 已成功运行。
9. 打开 codespace.md 文件，确认其中新增了以下内容：

   Writing code upon codespace creation!
   

10. 等待约 20 秒后刷新当前页面，GitHub Actions 会自动识别并进入下一步。

Step 4: 个性化你的 Codespace!

很棒!你已经完成了 Codespace 的基础设置! 🥳

工欲善其事，必先利其器。无论是使用本地还是云端开发环境，按照自己的喜好和工作流来调整设置与工具，是提升开发效率的重要一步。 GitHub Codespaces 提供了两种主要的个性化方式：使用 VS Code 的 Settings Sync（设置同步），以及使用 dotfiles（点文件）。

在本节中，我们将重点学习 dotfiles。

什么是 dotfiles? 它是一类在 Unix-like 系统中以 . 开头的文件或文件夹，用于控制系统上应用程序和 shell 的配置。 你可以在 GitHub 上创建一个仓库存放并管理这些 dotfiles，这样每次创建新的 Codespace 时，都能自动加载你喜欢的配置。

下面我们具体演示下!

⌨️ 实操环节: 启用 dotfile

1. 进入仓库主页。
2. 点击右上角的个人头像，选择 Settings（设置）。
3. 在左侧边栏的 Code, planning, and automation（代码、规划与自动化） 下，点击 Codespaces。
4. 在 Dotfiles 部分，勾选 Automatically install dotfiles（自动安装 dotfiles），让每个新建的 Codespace 都会自动应用你的 dotfiles。
5. 点击 Select repository（选择仓库），然后选择当前的课程仓库作为安装 dotfiles 的来源。

⌨️ 实操环节: 向仓库添加一个 dotfile 并运行 Codespace

1. 进入仓库主页。

2. 点击页面中间的 Code 按钮。

3. 在弹出的窗口中选择 Codespaces tab。

4. 点击 Create codespace on main（在 main 分支上创建 Codespace）。

   需要等待大约 2 分钟，环境会自动启动。

5. 确认你的 Codespace 已经运行。此时浏览器应打开一个基于 VS Code 的在线编辑器，并带有终端窗口，例如下图所示：

   

6. 在 VS Code 的文件管理器中创建一个新文件：setup.sh。

7. 在文件中输入以下内容：

   #!/bin/bash
   
   sudo apt-get update
   sudo apt-get install sl
   echo "export PATH=\$PATH:/usr/games" >> ~/.bashrc
   

8. 保存文件。

   提示：VS Code 会自动保存。

9. 在终端中执行以下命令提交文件：

   git add setup.sh --chmod=+x
   git commit -m "Adding setup.sh from the codespace!"
   

10. 将更改推送到远程仓库：

    git push
    

11. 返回仓库主页，确认 setup.sh 文件已成功上传。

12. 关闭当前的 Codespace 页面。

13. 再次点击 Create codespace on main 按钮创建新环境。

    等待约 2 分钟，环境将再次自动启动。

14. 确认 Codespace 已运行，并且 setup.sh 文件已出现在编辑器中。

15. 在终端中输入以下命令：

    sl
    

16. 你的终端上会出现一个 “跑火车” 的动画。

17. 等待约 20 秒后刷新此页面（即你当前查看的教程页面）。GitHub Actions 会自动检测进度并跳转到下一步。

完成

恭喜你！你已经完成了本课程!

回顾一下，你在本课程中完成了以下内容：

• 学会了如何创建 Codespace，并在其中将代码推送到仓库。
• 学会了在 Codespace 中使用自定义镜像。
• 学会了如何调整 Codespace 的配置。
• 学会了如何个性化你的 Codespace。

延伸学习与资源

• 在 Codespace 中开发：了解如何删除或重新打开 Codespace、连接私有网络、端口转发等。
• 设置你的仓库：学习如何为 Codespace 设置最低规格、添加徽章、建立模板仓库等。
• 个性化与自定义 GitHub Codespaces：了解如何同步设置、添加 dotfiles、指定默认区域和编辑器等。
• 预构建 Codespace
• 管理 Codespace

接下来可以做什么？

• 阅读 GitHub Codespaces 概述，了解如何保障供应链安全。
• 在 课程讨论区 分享你的学习体验。
• 前往 GitHub Skills 学习更多技能。
• 查阅 GitHub 入门文档。
• 想参与开源？来 GitHub Explore 发现有趣的项目吧！