Codespaces 是 GitHub 托管的远程开发环境，VSCode 仅作为前端通过官方扩展连接；需安装 github.codespaces 扩展、登录有权限的 GitHub 账户，并用专用命令连接或重建容器，环境配置由 devcontainer.json 驱动且必须提交到仓库。
Codespaces 在 VSCode 里不是“插件”，而是远程开发环境的入口
VSCode 本身不“运行” Codespaces，它通过 Remote - SSH 或官方 GitHub Codespaces 扩展（由 GitHub 官方维护）连接到云端已启动的容器实例。你本地 VSCode 只是图形前端，所有代码、终端、调试器实际运行在 GitHub 托管的 Linux 容器中。
常见错误现象：Command 'Codespaces: Create New Codespace' not found——说明没装对扩展，或没登录 GitHub 账户。
- 必须安装
GitHub Codespaces扩展（ID：github.codespaces），不是第三方仿制版 - 登录需点击左下角账户图标 →
Sign in to GitHub，且该账号需有 Codespaces 访问权限（免费用户每月 60 小时，私有仓库需 GitHub Pro/Team） - 首次使用建议从 GitHub.com 页面点
Code → Open with Codespaces → Create codespace on main，再用 VSCode 连接，避免本地配置干扰
打开已有 Codespace 时，VSCode 提示 “Reopen in Codespaces” 是关键入口
这不是提示你“重开窗口”，而是 VSCode 检测到当前文件夹关联了 GitHub 仓库，并且该仓库已有活跃的 Codespace 实例。点击后，VSCode 会断开本地工作区，切换为远程连接模式，加载远程容器中的完整环境。
容易踩的坑：Ctrl+P 输入 Remote-SSH: Connect to Host... 无法连 Codespace——因为 Codespaces 不走 SSH 配置，必须用专用命令。
- 正确路径：命令面板（
Ctrl+Shift+P）→ 输入Codespaces: Connect to Existing Codespace - 若列表为空，检查 GitHub.com 上是否真有运行中的实例（
https://github.com/codespaces） - 连接后左下角状态栏会显示
codespace (your-repo-name)，此时所有操作（包括git commit、npm install）都在远程执行
自定义 devcontainer.json 是控制 Codespace 环境的核心，不是可选项
没有 .devcontainer/devcontainer.json，Codespaces 会用默认 Ubuntu + 基础工具链启动，大概率缺编译器、语言运行时或特定 CLI。所有环境定制（Python 版本、Node.js 版本、预装 apt 包、端口转发）都靠这个文件驱动。
典型错误：改了 devcontainer.json 但重启 Codespace 后没生效——因为 Codespace 默认不会自动重建，需手动触发。
- 修改后必须执行
Codespaces: Rebuild Container（命令面板），否则仍运行旧镜像 -
image字段优先于dockerfile；若两者都存在，以image为准 - 端口转发要显式写进
forwardPorts数组，比如[3000, 8080]，否则浏览器打不开本地映射的localhost:3000 - 敏感配置（如 API key）绝不能硬编码进
devcontainer.json，应使用remoteEnv+ Codespaces secrets
本地 VSCode 设置（settings.json）和 Codespace 的设置是隔离的
你在本地启用了 editor.formatOnSave，不代表 Codespace 里也生效。Codespace 使用自己的设置副本，存储在远程容器的 /workspaces/your-repo/.vscode/settings.json 中，或由 devcontainer.json 的 settings 字段注入。
常见困惑：为什么在 Codespace 里装了 Prettier 插件，格式化还是不工作？
- 插件必须在
devcontainer.json的extensions数组里声明，例如"esbenp.prettier-vscode"，否则只装在本地 VSCode - 推荐把团队共用设置（如缩进、保存行为）写进
devcontainer.json.settings，而非依赖个人 settings.json - 调试配置（
.vscode/launch.json）需放在仓库根目录下，Codespace 才能识别——它不会读你本地机器的全局 launch 配置
最常被忽略的是：Codespace 容器重启后，所有未提交的 .vscode/ 修改都会丢失。务必把 devcontainer.json、settings.json、launch.json 提交到仓库主分支。
