GitHub Codespaces 创建与环境配置指南（Python + Conda 环境）

本文档基于 llm-universe 项目需求，介绍如何在 GitHub 上创建和使用 Codespaces 云端开发环境。
前提：首先确认你能够流畅访问 GitHub 网站。如果网络不稳定，建议改用阿里云等国内服务。

一、什么是 Codespace？

Codespace 是 GitHub 提供的云端开发环境 （托管在云中的虚拟机）。你可以通过将配置文件（如 devcontainer.json）提交到代码仓库，实现"配置即代码"，为项目的所有成员提供完全一致、可重复的开发环境。

二、创建第一个 Codespace

步骤 1：进入 Codespaces 页面

打开浏览器，访问：github.com/features/co...
登录你的 GitHub 账户

步骤 2：准备一个代码仓库

Codespace 必须关联一个 GitHub 仓库。你可以使用现有仓库，也可以新建一个。

在 GitHub 首页或通过左上角菜单进入 Your repositories（你的仓库列表）。
点击 New 按钮，创建一个新仓库。
填写仓库设置：
- Repository name ：自定义，例如 llm-universe-env
- Description（可选）
- Public / Private ：建议选择 Private（因后续可能使用 API Key 等敏感信息，保护隐私）
- Initialize this repository with ：建议勾选 Add a README file（方便初始化）
点击 Create repository 完成创建。

步骤 3：从仓库创建 Codespace

进入刚创建的仓库页面。
点击绿色的 Code 按钮，切换到 Codespaces 标签页。
点击 Create codespace on main（基于主分支创建代码空间）。
等待几分钟（首次创建会拉取基础镜像并构建环境）。

步骤 4：使用 Codespace

创建完成后，会打开一个基于浏览器的 VS Code 界面。
该界面与本地 VS Code 几乎完全一致，你可以：
- 安装扩展插件
- 编辑代码
- 打开终端执行命令
后续再次进入该仓库的 Codespaces 列表，点击已有的 codespace 即可恢复工作。

三、环境配置注意事项

3.1 关于 Conda 和镜像源

不需要手动安装 Conda ：GitHub Codespaces 的默认镜像（Default Linux Universal）已经预装了 Miniconda。
不需要配置国内镜像源：因为 GitHub 服务器位于国外，直接使用官方源下载速度通常较快。如果你在国内遇到网络问题，可自行添加清华源等，但这不是必须的。

3.2 首次完成配置后建议重启

当你第一次安装完所有必需的扩展或完成环境初始化后，建议执行一次 Rebuild 或直接重启 Codespace：

通过命令面板（F1 或 Ctrl+Shift+P）搜索 Codespaces: Rebuild Container
或者关闭浏览器标签页，重新从仓库的 Codespaces 列表进入

这样可以确保所有配置正确生效。

3.3 终端基础配置（Conda 初始化）

Codespace 默认预装了 Miniconda ，但有时未完成 shell 初始化，导致 conda activate 无法使用。需手动执行一次初始化。

bash 复制代码

# 1. 初始化 conda 到当前 shell
conda init

# 2. 重新加载配置文件（二选一）
source ~/.bashrc      # 如果使用 bash
source ~/.zshrc       # 如果使用 zsh

# 3. 验证 conda 是否正常
conda --version

若出现版本号（如 conda 24.x.x），则表示成功。

配置 Conda 镜像源（可选，加速下载）

由于 GitHub Codespace 服务器位于国外，默认使用官方源通常速度尚可。若你感觉下载缓慢或出现 NoChannelsConfiguredError，可添加国内镜像源（以清华源为例）。

bash 复制代码

# 添加四个常用频道
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/

# 可选：显示下载来源的 URL
conda config --set show_channel_urls yes

这些命令是全局的，修改的是 ~/.condarc 文件，一次配置永久生效，与当前工作目录无关。

创建并激活 Python 虚拟环境

bash 复制代码

# 创建名为 llm-universe 的环境，指定 Python 3.10
conda create -n llm-universe python=3.10 -y

# 激活环境
conda activate llm-universe

# 确认当前环境
conda info --envs
# 激活的环境前面会有 * 号

若创建时遇到 NoChannelsConfiguredError，请先执行上一节的镜像源配置。

安装项目依赖

如果项目根目录有 requirements.txt，使用 pip 批量安装（建议使用国内镜像源加速）：

bash 复制代码

# 激活环境后安装所需的包
pip install -r requirements.txt

#可以通过清华源加速安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果尚未准备 requirements.txt，可手动安装需要的包，例如：

bash 复制代码

pip install numpy pandas jupyter

在 Codespace 中安装的所有包都会保存在云端环境中，关闭后重新打开依然存在（除非执行完全重建或删除环境）。

3.4 常见问题与解决

问题	解决方法
`conda activate` 报错 `Run 'conda init'`	在终端执行 `conda init`，然后 `source ~/.bashrc` 或新开终端。
`conda create` 提示 `NoChannelsConfiguredError`	添加 channel：`conda config --add channels conda-forge` 或使用国内源。
SSH 克隆私有仓库权限被拒	推荐在 Codespace 中使用 HTTPS 克隆（`git clone https://...`），无需配置 SSH。
终端无法识别 `conda`	确认你已在 Codespace 中（提示符含 `/workspaces/`），默认自带 conda。若没有，可手动安装 Miniconda。

四、使用本地 VSCode 连接 Codespace

如果你更喜欢本地 VSCode 的完整功能，可以通过官方插件远程连接。

安装插件
在本地 VSCode 扩展商店搜索并安装 GitHub Codespaces。
登录
安装后，点击左侧活动栏的 远程资源管理器 图标（Remote Explorer）。
按照提示登录 GitHub 并授权。
连接
在远程资源管理器中，你会看到你的所有 Codespace。
点击对应项目右侧的 连接图标 （一个 >< 符号）。
等待
VSCode 会重新加载窗口，并连接到云端环境。之后你可以像本地一样编辑、调试、运行终端命令。

首次连接可能需要安装一些服务器端组件，请耐心等待。

五、补充建议

为每个项目单独创建仓库和 Codespace：不同项目依赖隔离，避免环境冲突。
定期停止或删除不用的 Codespace：节省 GitHub 免费额度（每月有一定免费时长）。
善用 requirements.txt 或 environment.yml ：将依赖文件提交到仓库，团队成员创建 codespace 后可直接 pip install -r requirements.txt 或 conda env create -f environment.yml。

GitHub Codespaces 创建与环境配置指南（Python + Conda 环境）