GitHub Codespaces

GitHub Codespaces 是 GitHub 提供的云端开发环境，让你可以在浏览器或本地 VS Code 中快速启动一个配置完整的开发环境，无需在本地安装任何工具。

概述

Codespaces 为每个项目提供一个运行在云端的完整开发环境。这个环境是一个 Docker 容器，可以根据项目需求进行配置，包含所需的语言、工具、依赖和扩展。

核心优势

即时启动：无需在本地配置环境，点击即可开始编码。对于大型项目或复杂依赖的项目，这可以节省大量初始配置时间。

环境一致性：团队成员使用相同的环境配置，避免了"在我机器上能运行"的问题。所有人都使用相同的工具版本和配置，减少了环境相关的调试时间。

资源弹性：云端环境可以根据需求选择不同的配置（2 到 32 核心），本地机器性能不再是限制。处理计算密集型任务时可以选择高配置，日常开发则选择低配置节省成本。

随处访问：只需要一个浏览器就能工作。可以在任何设备上访问你的开发环境，包括平板电脑或其他人的电脑，所有工作状态都会保留。

使用场景

• 新成员入职：新团队成员无需配置本地环境，直接启动 Codespaces 即可开始工作
• 开源贡献：贡献者无需安装项目所需的全部工具链，直接在 Codespaces 中开发和测试
• 临时开发：在临时设备上需要紧急修复 bug 或查看代码
• 代码审查：在完整环境中运行和测试 PR 的代码变更
• 学习和实验：学习新技术或框架时，快速搭建干净的学习环境

定价与额度

Codespaces 按使用时间和存储计费：

项目	免费额度（个人账户）
计算时间	每月 120 小时（2 核心标准）
存储	每月 15 GB

对于组织和团队版，计费基于实际使用量。创建 Codespace 时可以选择不同的机器配置，配置越高，每分钟消耗的额度越多。

快速开始

创建 Codespace

在 GitHub 仓库页面：

1. 点击绿色的 Code 按钮
2. 选择 Codespaces 标签
3. 点击 Create codespace on main（或选择其他分支）

首次创建可能需要几分钟来配置环境。环境就绪后，会打开一个网页版的 VS Code 编辑器。

从模板创建

GitHub 提供了快速启动模板，适合学习和实验：

1. 访问 github.com/codespaces
2. 点击 Use this template
3. 选择一个模板（如 React、Node.js、Python 等）
4. 启动后会创建一个临时仓库

使用 GitHub CLI

# 列出所有 codespaces
gh codespace list

# 创建新的 codespace
gh codespace create --repo owner/repo

# 连接到 codespace
gh codespace connect

# 停止 codespace
gh codespace stop

# 删除 codespace
gh codespace delete

在 VS Code 中打开

Codespace 可以在本地 VS Code 中打开，享受完整的桌面体验：

1. 安装 GitHub Codespaces 扩展
2. 在 VS Code 中按 Ctrl+Shift+P，输入 "Codespaces: Connect to Codespace"
3. 选择要连接的 Codespace

连接后，VS Code 会像打开本地项目一样工作，但实际运行在云端。

Dev Container 配置

Dev Container 定义了 Codespace 的开发环境配置。配置文件放在仓库的 .devcontainer 目录下。

基础配置结构

创建 .devcontainer/devcontainer.json 文件：

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu"
}

这是最简单的配置，使用微软提供的基础镜像。基础镜像包含了常用的开发工具。

使用 Dockerfile

对于复杂的环境需求，可以自定义 Dockerfile：

Dockerfile：

FROM node:20-bookworm

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    git \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# 安装全局 npm 包
RUN npm install -g pnpm typescript

# 设置工作目录
WORKDIR /workspace

devcontainer.json：

{
  "name": "Node.js Project",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    }
  }
}

使用 Features 快速添加工具

Features 是预定义的工具安装脚本，可以快速添加语言和工具到环境中：

{
  "name": "Full Stack Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    },
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.12"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

常用的 Features 包括：

Feature	说明
node	Node.js 运行时
python	Python 运行时
java	JDK
go	Go 语言
docker-in-docker	Docker 支持
github-cli	GitHub CLI
terraform	Terraform
aws-cli	AWS CLI

配置 VS Code 扩展

自动为团队成员安装必要的 VS Code 扩展：

{
  "name": "TypeScript Project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-sqlite",
        "esbenp.prettier-vscode",
        "ms-vscode.vscode-typescript-next",
        "formulahendry.auto-rename-tag"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "typescript.preferences.importModuleSpecifier": "relative"
      }
    }
  }
}

生命周期命令

配置环境初始化脚本：

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "postCreateCommand": "npm install",
  "postStartCommand": "npm run build",
  "postAttachCommand": "npm run dev"
}

生命周期钩子说明：

命令	执行时机	用途
onCreateCommand	创建容器时（仅一次）	安装系统级依赖
updateContentCommand	更新内容时	拉取最新代码后重新安装依赖
postCreateCommand	创建完成后	安装项目依赖
postStartCommand	每次启动时	启动服务
postAttachCommand	连接编辑器后	启动开发服务器

多配置支持

大型仓库可以为不同项目提供多个开发配置：

.devcontainer/
├── devcontainer.json          # 默认配置
├── frontend/
│   └── devcontainer.json      # 前端开发配置
└── backend/
    └── devcontainer.json      # 后端开发配置

创建 Codespace 时可以选择使用哪个配置。

Prebuilds 预构建

对于大型项目，每次创建 Codespace 都需要下载依赖和配置环境，可能需要较长时间。Prebuilds 通过预构建环境快照来加速 Codespace 创建。

为什么使用 Prebuilds

如果你的项目创建 Codespace 需要超过 2 分钟，就应该考虑使用 Prebuilds。Prebuilds 会预先执行以下操作：

• 克隆仓库代码
• 安装项目依赖
• 执行配置命令（onCreateCommand 和 updateContentCommand）

当你创建新的 Codespace 时，直接使用预构建的快照，只需几秒钟就能启动。

配置 Prebuilds

在仓库设置中配置：

1. 进入仓库 Settings > Codespaces
2. 点击 Set up prebuild
3. 配置选项：
   • 选择分支
   • 选择触发方式（每次推送、定时、手动）
   • 选择区域
   • 选择机器类型

配置完成后，GitHub Actions 会自动创建预构建。

通过 API 配置

也可以通过 GitHub API 配置 Prebuilds：

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  /repos/{owner}/{repo}/codespaces/prebuild-configurations \
  -f configuration='{"location":"WestUs2","settings":{"prebuild_interval":60}}'

Prebuilds 更新策略

Prebuilds 可以配置自动更新：

• 每次推送更新：默认方式，推送代码后自动更新预构建
• 定时更新：每小时、每天或每周更新一次
• 手动更新：仅在需要时手动触发

对于频繁推送的仓库，建议使用定时更新，避免消耗过多资源。

端口转发

Codespace 运行的服务可以通过端口转发从外部访问，适合预览 Web 应用或调试 API。

自动端口转发

当代码中启动服务时，Codespaces 会自动检测并转发端口：

// 启动开发服务器
app.listen(3000, () => {
  console.log('Server running on port 3000')
})

VS Code 会弹窗提示检测到新端口，点击即可在浏览器中打开。

手动转发端口

在 VS Code 的 Ports 面板中：

1. 点击 Forward a Port
2. 输入端口号
3. 端口会显示在列表中

端口可见性

转发的端口可以设置为不同可见性：

可见性	说明
Private	仅自己可访问
Org	组织成员可访问
Public	任何人可通过链接访问

通过点击端口的可见性设置来修改。

共享端口 URL

可以共享端口 URL 让他人访问你的应用：

# 使用 gh 命令获取端口 URL
gh codespace ports

Secrets 管理

Codespaces 可以安全地访问敏感配置，如 API 密钥和数据库凭据。

仓库级 Secrets

在仓库设置中添加：

1. 进入仓库 Settings > Secrets and variables > Codespaces
2. 点击 New repository secret
3. 输入名称和值

组织级 Secrets

组织管理员可以为所有仓库设置 Secrets：

1. 进入组织 Settings > Secrets and variables > Codespaces
2. 配置哪些仓库可以访问

在 Codespace 中使用

Secrets 会作为环境变量自动注入：

# 在终端中访问
echo $API_KEY

# 在代码中访问
const apiKey = process.env.API_KEY

允许仓库访问 Secrets

对于 Fork 的仓库，需要显式授权才能访问 Secrets：

1. 进入仓库 Settings > Codespaces
2. 在 Secrets 部分管理授权

个性化配置

Dotfiles 支持

Codespaces 可以自动应用你的 dotfiles 配置：

1. 创建一个 dotfiles 仓库，包含 install.sh 脚本
2. 在 GitHub 设置中配置 Dotfiles 仓库
3. 新建 Codespace 时会自动运行安装脚本

Dotfiles 可以包含：

• Shell 配置（.bashrc, .zshrc）
• Git 配置
• Vim/Neovim 配置
• 自定义脚本和别名

Settings Sync

VS Code 的 Settings Sync 功能可以在 Codespaces 间同步个人设置：

• 主题和图标
• 键盘快捷键
• 用户代码片段
• 语言设置

在 VS Code 中启用 Settings Sync 后，这些设置会自动应用到所有 Codespaces。

最佳实践

保持配置简洁

devcontainer.json 应该只包含团队共需的配置，不要加入个人偏好：

// 好的做法：团队必需的扩展
{
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-sqlite",
        "ms-azuretools.vscode-docker"
      ]
    }
  }
}

// 不好的做法：个人偏好的主题
{
  "customizations": {
    "vscode": {
      "extensions": [
        "dracula-theme.theme-dracula",  // 个人偏好
        "PKief.material-icon-theme"     // 个人偏好
      ]
    }
  }
}

个人偏好应该通过 Settings Sync 或 dotfiles 来配置。

使用 Prebuilds 加速

对于大型项目，始终配置 Prebuilds：

// .github/workflows/codespace-prebuild.yml
{
  "name": "Codespaces Prebuild",
  "on": {
    "push": { "branches": ["main"] }
  },
  "jobs": {
    "prebuild": {
      "runs-on": ubuntu-latest,
      "steps": [
        { "uses": "actions/checkout@v4" },
        { "run": "npm ci" }
      ]
    }
  }
}

及时清理不用的 Codespaces

Codespaces 会持续消耗存储配额，养成清理习惯：

# 列出所有 codespaces
gh codespace list

# 删除不再需要的
gh codespace delete codespace-name

或者在 GitHub 设置中配置自动删除策略：

• 自动删除天数：设置停止后的 Codespaces 自动删除时间

合理选择机器类型

根据任务选择合适的配置：

任务类型	推荐配置
日常开发	2 核心（默认）
构建测试	4 核心
数据处理	8 核心
机器学习	16-32 核心

使用恢复模式

如果配置错误导致 Codespace 无法启动，会自动进入恢复模式：

1. 查看 Creation Log 诊断问题
2. 修复 devcontainer.json 配置
3. 点击 Rebuild Container 重试

常见问题

Codespace 创建太慢

解决方案：

1. 配置 Prebuilds 预构建
2. 简化 Dockerfile，减少安装步骤
3. 使用预定义的 dev container 镜像
4. 将耗时的操作移到 postStartCommand（并行执行）

端口无法访问

检查：

1. 端口是否正在监听
2. 端口可见性设置
3. 防火墙是否阻止（检查应用配置）

权限问题

如果遇到权限错误：

1. 确保 Secrets 已正确配置
2. 检查仓库访问权限
3. 验证 GITHUB_TOKEN 是否有足够权限

磁盘空间不足

Codespace 默认有 32GB 存储。如果空间不足：

1. 清理不需要的文件和依赖
2. 使用 .devcontainer.json 的 workspaceFolder 设置
3. 考虑删除旧的 Codespaces

参考资源

• GitHub Codespaces 官方文档
• Dev Container 规范
• Dev Container Features
• VS Code Codespaces 扩展