GitHub Codespaces
开发者在浏览器里关闭了编辑器，第二天成本报表却仍有新增用量；另一个人删除实例后才发现半天的代码从未 push；第三个人把调试端口改成 public，误以为链接仍受 GitHub 登录保护。这三类事故来自同一个认知错误：把 Codespaces 当作一个网页编辑器，而不是一组有所有权、凭证、网络入口、计算资源和持久存储的云资源。
创建 Codespace 时，GitHub 会准备虚拟机和开发容器、挂载持久工作区、签发受限仓库 token、注入被授权的 Secrets，并为端口建立代理。浏览器、VS Code Desktop、JetBrains Gateway 和 GitHub CLI 只是连接入口；关闭窗口、停止实例、重建容器和删除实例是四个不同动作，成本与数据后果也完全不同。
先准备一个有权访问的示例仓库，并在创建对话框确认仓库、分支、实例 owner 和付款人。组织私有仓库还会受到 Codespaces access、所有权、预算以及成员或协作者范围约束，不能由“仓库属于组织”推导“组织一定买单”。GitHub CLI 应从官方安装入口获取，升级后先记录版本和认证状态：
gh --version
gh auth status
gh codespace --help预期 gh auth status 显示目标 GitHub host 和登录账号，帮助中存在 create、list、stop、delete 等子命令。CLI 若提示缺少 codespace scope，应按组织授权流程补充；不要运行会把 token 明文送入日志的 gh auth token。免费额度、单价、machine 列表和套餐能力会变化，创建前应查看当前计费规则和界面实际显示的付款主体。
创建来源先于编辑器入口
最常见的是从仓库 Code | Codespaces 选择分支后创建。创建入口说明同时列出了仓库页面、github.com/codespaces/new、VS Code 和 CLI。高级选项可以选择分支、多个 devcontainer.json 之一、区域和可用 machine；创建页会明确显示计费主体。https://github.com/codespaces/new 适合为任意有权限的仓库和分支选择参数。
CLI 适合脚本化创建：
gh codespace create \
-r your-org/your-project \
-b feature/example \
--devcontainer-path .devcontainer/devcontainer.json \
-m <available-machine><available-machine> 必须替换成当前仓库真实可用的 machine ID。命令会显示谁付费，并可能要求选择区域或授权额外权限。先交互式运行一次比把猜测的 machine 名写进脚本更稳妥。
另一类来源是 GitHub 提供的空白/技术模板或 template repository。模板型 Codespace 在发布前未绑定 GitHub 仓库，工作只存在云 VM 中；发布后会创建个人账号下的新仓库，所有权与计费也可能从组织转到用户。维护模板仓库本身时，应从仓库 Code 菜单创建，而不是 Use this template。
还可以从 pull request 或 fork 分支创建。此时仓库 token、Secrets 和写入目标会按公有/私有 fork 关系收窄。不要用“界面里能看到上游仓库”推断当前 token 能写上游。
所有权、付款人与策略控制
所有权与付款规则把 Codespace owner 与费用、策略控制关联起来。owner 可以是创建者个人，也可以是组织；用户不能在创建时任意指定付款人，组织通过 Codespaces access、ownership 和预算决定符合条件的成员或协作者是否由组织承担。
组织要付费，通常需要处于支持的 Team 或 Enterprise Cloud 计划、为用户启用 Codespaces、选择组织所有权，并具有允许支出的预算。组织 Free 不能替成员支付，实例由用户拥有和付费。即使仓库属于组织，只要用户不在组织启用范围、预算不允许，或实例属于用户，也可能落到个人账单。
所有权还决定管理能力。组织拥有的 Codespace 可由组织 owner 通过 API 停止或删除，可进入组织审计日志，也能受 machine、镜像、端口、空闲超时和保留期等策略约束。用户拥有的 Codespace 即使来自组织仓库，组织也没有同等实例管理能力。
这里有一条必须写进团队制度的覆盖边界：Codespaces 组织策略只适用于由组织付费的 Codespace。成员为组织仓库自费创建的用户所有实例，不受这些策略约束。 因此“仓库在组织里”不是完整安全控制；对敏感仓库要同时设计访问条件、所有权、预算和禁止旁路的制度。
所有权模式切换还可能转移既有实例。组织转为用户所有时，现有组织实例会转给创建者并开始消耗个人额度或费用；反向切换只会转移满足成员/协作者和启用条件的实例。变更前必须盘点实例、未推送工作、预算和通知，不能只改一个开关。
用 Dev Container 固化真实项目环境
没有 devcontainer.json 时，Codespaces 使用默认 Linux 镜像，适合快速试用，不足以成为团队可复现合同。Dev Container 配置应把运行时、初始化、端口和扩展放入仓库评审。
以下最小配置用于一个 Node.js 项目：
{
"name": "your-project-codespace",
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
"forwardPorts": [3000],
"portsAttributes": {
"3000": {
"label": "app-preview",
"visibility": "private"
}
},
"postCreateCommand": "npm ci",
"remoteUser": "node"
}把文件放在 .devcontainer/devcontainer.json。image 应固定到团队验证过的版本或 digest；浮动 tag 会让同一提交在不同日期得到不同工具链。postCreateCommand 在用户 Codespace 创建后执行，适合安装依赖；它不是秘密注入脚本，也不应执行来源不明的远程 curl | sh。
提交配置后创建新 Codespace，或在现有实例中执行 rebuild。普通 rebuild 会复用缓存；遇到镜像污染或基础层变化时再做 full rebuild。官方生命周期说明：rebuild 会清除 /workspaces 外的修改，保留 /workspaces 内仓库内容；所以手工安装到系统路径的工具不是可靠状态。
最小验证与预期结果
进入 Codespace Terminal 后先证明自己确实在目标实例：
printf 'codespace=%s\nrepo=%s\n' "$CODESPACE_NAME" "$GITHUB_REPOSITORY"
node --version
git status --short --branch预期 CODESPACE_NAME 非空，GITHUB_REPOSITORY 指向目标仓库，Node 主版本符合镜像合同，Git 位于所选分支。变量不符时不要继续写代码，应删除误建实例并从正确来源重建。
接着按仓库合同运行：
npm ci
npm test
npm run dev -- --host 0.0.0.0预期依赖按 lockfile 安装，测试退出码为 0，开发服务监听 3000。Ports 面板应出现 app-preview；默认 private，打开 GitHub 生成的转发 URL 后能看到项目响应。浏览器模式下在本机直接访问 localhost:3000 不等价于 Codespace 转发地址。
验证完成后终止开发进程，确认 Ports 面板不再转发不需要的端口。把有价值的更改提交并 push 到远端分支：Codespace 文件系统不是备份，删除实例会删除未推送工作。
Machine、Storage 与生命周期
machine 决定 CPU、内存、存储规格和 compute 费率。创建时默认选择满足仓库要求的最低可用规格；团队可以在 devcontainer.json 设置最低主机要求，组织也可以限制可选 machine。最低要求过高会让每次创建都进入更贵规格，过低则会让依赖安装、编译和索引反复失败。
查看实例与 machine：
gh codespace list
gh api /user/codespaces/<codespace-name>
gh api /user/codespaces/<codespace-name>/machines不要把 API 输出原样贴进公开工单，其中可能包含仓库、owner 和实例信息。变更 machine 使用：
gh codespace edit --machine <available-machine>同存储容量的变更通常在下次重启生效；存储容量不同会停止实例并短暂不可用。扩容不能替代清理构建产物，也不能保证之后能无损缩回更小磁盘。
Codespace 生命周期的四个动作要分清：关闭编辑器只是断开，实例仍会运行到空闲超时；stop 会停止进程和 compute 计费，但保留存储；rebuild 重新创建开发容器并保留 /workspaces；delete 才结束实例并停止后续 storage 累积。
官方当前默认空闲 30 分钟后停止、停止后默认保留 30 天再自动删除，个人和组织可在允许边界内调整。每个 Codespace 的 retention 在创建时确定，不会因为之后修改默认值自动改变。团队不要把默认值当 SLA，应设置符合分支寿命和数据分类的更短保留期。
Prebuild：用额外成本换启动速度
Prebuild 配置针对“仓库 + 分支 + devcontainer.json + 区域”预先创建环境，执行到 onCreateCommand 和 updateContentCommand，让新实例少做重复安装。它不是全局缓存，也不能保证任意 feature 分支都命中。
耗时且能安全共享的基础安装放入镜像、onCreateCommand 或 updateContentCommand；包含用户身份、个人 token、分支状态的动作留到创建后。GitHub Actions workflow 负责生成 prebuild，生成过程消耗 Actions minutes，产物存在期间计入 storage。
Prebuild 构建阶段不能使用用户级 Codespaces Secret，只能使用被授权的仓库级或组织级 Codespaces Secret。任何写入镜像层、日志或缓存的 Secret 都可能扩大泄露面。私有 registry 认证应使用专用、只读、短期凭证，并检查构建日志没有输出值。
如果最新 prebuild 失败，平台在部分情况下可能回退到旧 prebuild；配置也可选择在最新构建失败或运行时不用 prebuild。排障时检查目标分支、配置路径、区域、最近 Codespaces Prebuilds Actions 运行和配置变更，不能只凭创建页“很快”判断命中了新产物。区域数与保留版本数会相乘形成存储份数；设置页允许保留有限个历史版本，团队应按回退需求选择，而不是把所有区域和历史都当作免费保险。
Secrets 与仓库权限
Codespaces development environment secrets可以定义在用户、仓库或组织层，并在实例运行后作为环境变量出现。用户 Secret 要显式授权仓库；组织 Secret 也应限制到需要的仓库。新建或修改 Secret 后，正在运行的实例需要 stop 再 start 才会得到新值。
同名 Secret 按更低、更具体层级覆盖，例如 repository 覆盖 organization。团队应禁止同名多层漂移，否则开发者看到变量存在，却不知道来自个人还是组织。验证只检查是否存在，不输出明文：
test -n "$EXAMPLE_API_TOKEN" && echo 'secret-present'预期只出现 secret-present。不要 echo 值，不要写入 shell history、.env、镜像层、测试快照或诊断日志。删除或轮换 Secret 后，应重启实例并撤销服务端旧凭证；仅从 GitHub 设置删除变量不能让已泄露 token 失效。
Codespace 默认获得来源仓库的受限 token，权限会随只读仓库、fork 和发布模板等场景变化。若 devcontainer.json 请求其他仓库权限，创建者会看到授权页面；变更只影响新 Codespace，不会因 rebuild 自动扩权现有实例。your-org/* 之类通配授权会放大供应链影响，prebuild 还要求逐仓库声明，团队应优先最小化到具体仓库和只读权限。
端口可见性不是“分享链接”
Codespaces 端口安全模型规定转发端口默认 private，访问者需要认证。organization 可见要求适用的组织计划，并允许同组织成员访问；public 则任何知道 URL 的互联网用户都能访问，不需要 GitHub 认证。
公开前先问服务是否包含调试器、管理页面、内存数据、开发数据库或自动登录。即使只分享几分钟，也可能被扫描。组织应通过策略禁用 public 或 organization 可见性，只留下 private；private 不能完全禁用，因为 Codespaces 本身依赖私有转发，包括 SSH。
端口策略更新对不合规的运行实例通常在其停止或超时后、下一次恢复时生效，不是瞬时切断。public 端口在移除重加或重启后会恢复 private，不能把临时 UI 状态写成长期发布配置。代码若需要推导转发域名，应读取 GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN 等平台变量，不要硬编码 app.github.dev URL。
真实项目接入与提效
团队接入应让本地 Dev Container 与 Codespaces 尽量共享同一个规范，而不是维护两套安装脚本。把运行时、系统依赖、Feature、扩展、端口标签和非秘密初始化纳入代码评审；把个人 dotfiles、编辑器偏好和用户 Secret 留在个人层；把组织 CA、私服和开发服务凭证交给平台层。
开发流程可以约定“一任务一短寿命 Codespace”：从目标 branch 创建，运行仓库 bootstrap、测试和调试，及时 push，任务结束删除。大型仓库可以保留少量长寿命实例，但每次恢复先 pull 默认分支并检查 devcontainer 是否变化；配置变化后优先新建或 rebuild，不要让手工修补长期积累。
常用 CLI 闭环如下：
gh codespace list
gh codespace ssh -c <codespace-name>
gh codespace stop -c <codespace-name>
gh codespace delete -c <codespace-name>这些命令适合批量盘点和明确退出，不应在共享脚本里自动选择“第一个实例”。始终指定 permanent name，并在删除前检查分支是否已 push。
常见失败与故障闭环
创建按钮不可用或无法恢复
组织仓库没有创建入口，或已有实例无法 start。 检查仓库可见性、账号权限、组织 Codespaces access、ownership、预算和当前计费主体。 用户未被启用、预算用尽、个人额度用尽、仓库禁止 fork，或账号不满足计划边界。 由 owner 调整正确的访问与预算；需要抢救工作时使用官方 export-to-branch 能力，不要绕到个人账号复制敏感代码。 创建页明确显示付款人，实例可创建或恢复。
Rebuild 后工具和文件消失
手工安装的 CLI、配置或数据在 rebuild 后不见。 确认文件是否在 /workspaces 外，以及安装是否写入 Dockerfile、Feature 或 lifecycle command。 把容器可写层当持久工作区。 把可复现依赖提交到 devcontainer；敏感配置改为 Secret，业务数据改用批准的开发数据源。 full rebuild 后测试仍通过，不依赖手工命令。
Prebuild 存在但创建仍很慢
创建页没有命中预期 prebuild，或依赖仍重新安装。 核对分支、配置文件、区域、最新 workflow 状态和 updateContentCommand。 组合不匹配、最新配置构建失败、区域未覆盖，或耗时动作放在 postCreateCommand。 修正触发范围和生命周期命令，评估 storage 与 Actions 成本后再扩大区域。 创建页显示命中 prebuild，启动日志不再重复重活。
Secret 缺失或仍是旧值
环境变量不存在，或轮换后实例继续使用旧凭证。 检查 Secret 层级、仓库授权、同名覆盖和实例是否完成 stop/start。 只改了设置未重启、用户 Secret 不可用于 prebuild，或 repository Secret 覆盖组织值。 收敛 Secret 来源，调整授权并重启；服务端撤销旧 token。 仅用 test -n 验证存在，再执行最小权限 API 操作。
停止后费用仍增长
实例已 stopped，账单仍有 Codespaces 用量。 区分 compute、实例 storage、prebuild storage 和 prebuild Actions minutes。 stop 只停止 compute；实例和 prebuild 仍占存储，月内已累计费用也不会因删除倒扣。 push 工作后删除无用实例，清理过期 prebuild，缩短 retention，并检查预算和用量报表。 实例列表和 prebuild 列表无残留，后续小时不再新增相应 storage 用量。
供应链风险从 devcontainer.json 开始。基础镜像、Features、扩展、apt/npm 安装脚本和 prebuild workflow 都能在持有仓库 token、网络和部分 Secrets 的环境执行。只打开可信仓库；镜像和 Feature 固定版本或 digest；审查 lifecycle command；外部 PR 不自动获得敏感 Secret；新增跨仓库权限必须单独评审。
成本风险来自“创建方便、删除困难”。compute 只在运行时计费，但 stopped 实例、custom dev container 和 prebuild 继续形成 GB-hour；prebuild 还消耗 Actions minutes。团队要同时看实例数、machine 核心数、空闲超时、保留期、prebuild 分支/区域数量和 custom image 体积，而不是只设一个月度预算。
数据风险来自云 VM 里的未推送代码和开发数据。删除 Codespace 会删除未推送工作；移除用户访问后，私有仓库实例可能很快进入无法访问和删除流程。离职、外包到期和仓库迁移前，应先通知 push/export，再撤权和删除，不能依赖事后向支持恢复。
网络风险也不能由“默认私有端口”一笔带过。GitHub 当前官方私网文档仍提示，无法完全限制 Codespace 访问公共互联网；组织端口策略又不覆盖用户自费实例。高敏感代码若要求严格 egress、私网数据和统一策略，必须评估企业网络能力和组织所有权是否足够，否则选择受控自托管开发环境。
团队治理与退出
组织基线至少定义：允许创建的用户和仓库、必须组织所有还是允许自费、预算与告警 owner、machine allowlist、最低规格、base image 约束、空闲超时、retention、最大实例数、端口可见性、Secret owner、跨仓库权限、prebuild 分支与区域、镜像更新和退役流程。
一次规范退出按以下顺序执行：保存文件，运行测试，提交并 push；停止应用和端口；记录需要保留的分支；执行 gh codespace stop 观察状态；任务结束则执行 gh codespace delete；再检查仓库 prebuild、预算用量和 Secrets 是否仍有业务必要性。
删除实例不会冲减本月已累计费用，只会停止未来 storage 累积。删除个人 Codespace 也不会自动删除分支、仓库、组织 Secret、个人 Secret、prebuild 或 Actions 产物；这些是不同资源。真正的清理证据应包含实例列表、prebuild 列表、分支状态、Secrets owner 和后续用量趋势。
创建前已确认来源仓库、分支或模板，以及界面显示的所有者和付款人。已确认组织策略只覆盖组织付费 Codespace，没有把组织仓库等同于组织控制。已用仓库内 devcontainer.json 固化工具链，并能在 full rebuild 后复现。
已验证 CODESPACE_NAME、GITHUB_REPOSITORY、运行时、测试和 private 端口。已按实际可用列表选择 machine，没有写死猜测的规格或价格。已区分关闭、stop、rebuild、delete，对 compute、storage 和未推送工作影响明确。
Prebuild 的分支、配置、区域、Actions minutes、storage 和 Secret 边界已有 owner。Secrets 不输出明文，同名覆盖已收敛，旧凭证已在服务端撤销。public 端口默认禁用；组织策略变化和现有实例生效时点已验证。
已审查镜像、Features、扩展、生命周期脚本和跨仓库权限的供应链风险。删除后已检查实例、prebuild、分支、Secrets 与后续用量，没有把 stopped 当作零费用。