Codespaces

0. 从一个生活场景说起：云端电脑与远程办公#

过去，你要用电脑必须坐在自己那台”配置了好久的台式机”前：装系统、装编辑器、配环境变量、装依赖……换台新电脑就得重来一遍，还常常”在我电脑上好好的，在你电脑上就报错”。

GitHub Codespaces 改变了这个体验——它相当于一台放在云端的电脑：打开浏览器就能”远程办公”（写代码），环境配置写在”装修图纸”（devcontainer.json）里，团队任何成员都能一键复制出一模一样的开发环境。本篇采用体验驱动的结构：从”在浏览器里写代码”的第一印象开始，逐步深入原理（远程容器）、配置（devcontainer.json）、提速（预构建）与日常管理。

1. 体验起步：30 秒走进”浏览器里的 IDE”#

1.1 第一次创建 Codespace#

1. 打开任意 GitHub 仓库，点击绿色 Code 按钮。
2. 切换到 Codespaces 标签页。
3. 点击 Create codespace on main。
4. 等待几十秒，浏览器中出现一个完整的 VS Code 界面——代码已经打开，终端可用，git、Node.js/Python 等工具已就绪。
5. 直接写代码、跑测试、git commit、git push，全程不需要在本地安装任何东西。

1.2 三种打开方式#

2. 原理讲解：Codespaces 到底是怎么工作的#

2.1 直观理解：三层结构#

你的浏览器/VS Code（客户端）
        ↓ 远程连接（SSH / 端口转发）
云端虚拟机（专属于你的 Linux 机器）
        ↓ 里面运行
开发容器（dev container，Docker 容器）

• 每个 codespace 都运行在独立的云端虚拟机上，里面有一个 dev container（开发容器）——这是关键：你的开发环境整体打包在 Docker 容器中。
• 你在浏览器里看到的编辑器只是”遥控界面”，真正的代码、依赖、进程都在云端容器里运行。
• 容器与仓库绑定：任何人为这个仓库创建的 codespace，环境都一样——“在我电脑上好好的”从此成为历史。

2.2 关键概念：dev container#

• 开发容器是专门配置成完整开发环境的 Docker 容器，预装语言运行时、包管理器、git、常用 CLI 工具。
• 它的配置文件（devcontainer.json）放在仓库的 .devcontainer 目录中，随代码一起版本管理。
• 如果仓库没有配置，Codespaces 会使用默认容器配置（已包含多种语言运行时和常用工具）。
• 官方文档明确定义：“Whenever you work in a codespace, you are using a dev container on a virtual machine”——在 codespace 里工作，本质上就是在虚拟机里的开发容器中工作。

2.3 免费额度（个人账户参考）#

计费按”核心数 × 使用小时”计算：2 核机器跑 1 小时 = 2 核心小时。不用的 codespace 及时停止/删除可省额度。

2.4 从模板与多种入口创建#

• 从模板创建：GitHub 提供大量官方模板仓库（如 microsoft/vscode-remote-try-node），仓库页面点 Use this template → Open in a codespace 即可秒开一个预配置环境，适合学习与测试。
• 从任意分支创建：在仓库的 Branches 页面选择分支后创建 codespace，或 gh codespace create -b dev 指定分支。
• 从 Issue / PR 创建：在 Issue 或 PR 页面也可直接打开 codespace，直接针对该 Issue/PR 对应的代码工作，改完原地提交。

3. 配置开发环境：devcontainer.json#

3.1 最简配置：直接用现成镜像#

// .devcontainer/devcontainer.json
{
  "name": "My Node Dev Environment",
  // 使用官方预构建镜像（Node 20）
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  // 附加特性：安装 git 与 GitHub CLI
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  // 自动转发端口（浏览器访问 http://localhost:3000）
  "forwardPorts": [3000, 5173],
  // 容器创建完成后执行的命令（安装依赖）
  "postCreateCommand": "npm install",
  // VS Code 定制：自动安装扩展与设置
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  }
}

3.2 Dockerfile 方式：完全自定义#

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/javascript-node:20

# 安装项目需要的系统级工具
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get install -y postgresql-client

WORKDIR /workspace

// .devcontainer/devcontainer.json
{
  "name": "Custom Environment",
  "build": { "dockerfile": "Dockerfile" }
}

改完 devcontainer 配置后需要重建容器（VS Code 命令面板：Codespaces: Rebuild Container，或 gh codespace rebuild）才会生效。

4. 日常管理：从创建到回收#

# 创建（指定仓库与分支）
gh codespace create -r owner/repo -b main

# 列出所有 codespace
gh codespace list

# 查看详情 / 日志
gh codespace view
gh codespace logs

# 停止（停止计费！）
gh codespace stop

# 重建（应用 devcontainer 改动）
gh codespace rebuild

# 删除（清理额度）
gh codespace delete --force
gh codespace delete --days 7   # 删除 7 天前停止的

# 端口管理
gh codespace ports
gh codespace ports visibility 3000:public

4.1 端口转发：让云端服务可访问#

容器里的服务（如 npm run dev 启动的 3000 端口）通过端口转发暴露给你，浏览器直接访问 http://localhost:3000 即可——虽然服务在云端，体验如同本地。

4.2 个性化：dotfiles 与 Codespaces secrets#

• dotfiles（个人配置仓库）：在你的个人仓库创建一个名为 dotfiles 的公开仓库，把 .bashrc、.zshrc、.gitconfig 等配置文件放进去，并在 GitHub 的 Settings → Codespaces 中启用，之后每个新 codespace 都会自动应用你的个性化配置。
• Codespaces secrets（环境密钥）：需要注入容器的敏感信息（如 NPM token、云服务密钥），在 Settings → Codespaces → Codespaces secrets 或仓库级 Settings → Secrets and variables → Codespaces 中配置，容器内以环境变量形式使用，不进入代码仓库。

5. 提速技巧：预构建（Prebuilds）#

5.1 为什么要预构建#

没有预构建时，每次创建 codespace 都要现场安装依赖（npm install、构建产物），可能要等 5-10 分钟。预构建（prebuild） 在后台提前完成”镜像 + 依赖安装 + 构建”这些耗时步骤，创建时直接复用，启动可缩短到 30 秒左右。

5.2 配置预构建#

1. 仓库 Settings → Codespaces → Prebuilds → Set up prebuild。
2. 选择分支（生产常用 main）、devcontainer 配置、区域。
3. 设置触发条件：推送时触发 / 配置变更时触发。

5.3 生命周期命令的最佳分工#

在 devcontainer.json 中合理分配命令，把耗时的放预构建阶段：

• onCreateCommand：最耗时的操作（如 npm ci 安装依赖）——预构建时执行。
• updateContentCommand：随内容更新的构建（如 npm run build）。
• postCreateCommand：只依赖密钥/用户的个性化操作（尽量轻量）。

5.4 机器规格与成本估算#

创建 codespace 时可选择机器规格，规格越大越快也越费额度：

成本估算示例：Free 账户每月 120 核心小时。4 核机器每天用 2 小时，一个月约 240 核心小时——超过免费额度，需注意停止空闲环境或升级计划。

6. 常见错误与对策#

8. 一句话记忆#

Codespaces 是”云端电脑”：devcontainer.json 是环境图纸，容器保证团队环境一致，预构建把启动从 5 分钟压到 30 秒，用完记得停止和删除省额度。

延伸阅读#

• 在 codespace 中使用 GitHub CLI 操作仓库/PR，见 020 篇《GitHub CLI》。
• 容器与镜像相关概念，可参考 023 篇《GitHub Packages》。
• 云端环境下的 CI/CD 自动化，见 029 篇《GitHub Actions 与 CI/CD》。