在浏览器 IDE 中同步 GitHub：实用指南

浏览器项目之所以方便，正是因为它不需要文件夹、运行时或安装。同样的特性也是它的弱点。项目存放在浏览器配置文件中，可能被清理工具删除、随设备丢失，或在换电脑时被遗留。导出 ZIP 能创建副本，但 ZIP 是没有历史、没有共享远端的快照。GitHub 补上了缺失的一层：设备之外的仓库、提交历史、协作场所，以及 CI 或部署的自然来源。这改变了浏览器 IDE 的角色。它不再是一次性草稿本，而可以成为编写、审查和交接小型项目的地方。这套流程在 Chromebook、学校机房，或无法安装 Git 的公司锁定笔记本上尤其有用。对于之后可能迁移到桌面仓库的快速原型，它同样适用。浏览器负责第一稿，GitHub 让它持久。

GB Coder 提供三个 GitHub 操作：Push、New repo 和 Pull。Push 把当前项目写入现有仓库和分支。New repo 在已连接的 GitHub 账户下创建仓库，并把项目作为初始内容提交。Pull 读取分支，把文本文件导入编辑器。所有请求都从浏览器直接发往 api.github.com；LadeStack 服务器不会在中间持有令牌。这种有限的范围是有意为之。这个面板不能替代 Git 命令行。它不提供 rebase、合并冲突解决、子模块、Git LFS、签名提交、钩子或多远端。它也不显示完整的提交图。在复杂仓库中，这些限制很重要。对于常见的浏览器项目——静态页面、React 原型、教学示例或小型工具——这三个操作正好覆盖了标签页之外真正需要完成的部分。

GitHub 同步使用个人访问令牌，而不是密码，也不是 GB Coder 账户。经典令牌需要 repo 范围。细粒度令牌需要 Contents 的读写权限，并且可以限制到单个仓库。更窄的选项是更好的默认值：如果令牌泄露，损害会被限制在它能访问的项目内。连接界面会链接到 GitHub 的令牌页面，并解释这两种选择。粘贴令牌，选择是否在此设备上记住它，然后点击 Connect。GB Coder 会通过获取账户和仓库列表来验证令牌，然后显示登录名和剩余 API 速率限制。在确认 Push 或创建仓库之前，不会向仓库写入任何内容。请像对待密码一样对待令牌：不要粘贴到 issue、聊天或截图中，不再需要时在 GitHub 上撤销。设置过期时间并只访问一个仓库的令牌，是这套流程中合理的折中。

Push 标签页会要求选择仓库、分支、提交信息，以及一个可选项：删除项目中不存在的文件。在任何内容离开浏览器之前，面板会显示文件数量和总大小。这个预览很有用，因为上传并不是把编辑器标签页原样倒出去。GB Coder 使用与 ZIP 导出和部署相同的归档构建器。简单的 HTML/CSS/JavaScript 项目会变成 index.html、style.css、script.js 和 README。React 或 Vue 项目会变成 Vite 结构的仓库，包含 index.html、package.json、vite.config.js、.gitignore、README，以及 src/ 下的源文件。依赖目录和构建输出不会包含在内。提交信息可以编辑，默认是“Update from GB Coder”。删除缺失文件的选项默认关闭；只有当仓库应精确镜像当前项目时才打开，因为它会删除本地已不存在的远端文件。首次 Push 时，除非你刻意想要单独的分支，否则选择仓库的默认分支。

朴素的浏览器同步会一次提交一个文件。这会产生嘈杂的历史，而且如果请求中途失败，仓库会停留在只更新了一半的状态。GB Coder 改用 GitHub 的 Git Data API：上传 blob，在分支当前树之上构建树，创建一个提交，然后移动分支引用。结果是每次 Push 只有一个原子提交，包括删除选项请求的删除。第二个优化更安静，但同样重要。Git 用 SHA-1 哈希标识文件内容，浏览器可以用 WebCrypto 在本地计算该哈希。GB Coder 在上传前把本地文件与目标树进行比较。未更改的文件不消耗 API 调用，没有任何变化的 Push 会返回“already up to date”，而不是创建空提交。这让历史保持可读，并把 API 预算留给真正的更改。在小项目中差别看不出来；在拥有几十个文件的项目中，这就是干净同步与缓慢嘈杂同步的区别。

New repo 标签页会在已连接的账户中创建仓库。你提供名称和可选描述，选择公开或私有，并决定 GitHub 是否用 README 初始化仓库。初始化默认开启，因为空仓库没有可供首次 Push 构建的分支头。GB Coder 使用这个种子提交，用项目自己的文件替换 README，并记录初始提交。关闭初始化时，它会自行创建根提交和默认分支引用。创建后，新仓库和默认分支会被选中用于下一次 Push，因此没有第二轮设置。这是从想法到私有、受版本控制的仓库的最短路径。它适用于课堂作业、需要保持私密的客户演示，或需要为 CI 服务提供 URL 的原型。仓库属于持有令牌的 GitHub 账户，而不是 LadeStack，之后可以在 GitHub 上管理、转移或删除。

Pull 是返程。输入仓库 URL 或 owner/name 组合，选择分支，GB Coder 会读取分支树。它会导入编辑器能够有意义地打开的文本文件：源代码、JSON、Markdown、配置和 SVG 等。它会跳过 node_modules、dist、build、.git、.next 和 coverage 目录。Pull 还限制为 200 个文件、每个文件 512 KB；如果分支超过任一限制，面板会说明有多少文件被排除，而不是悄悄丢弃。行尾会被规范化，因此 Windows 创建的文件不会看起来每一行都变了。导入的文件不会立即覆盖项目。它们会经过与 ZIP 导入相同的审查和应用流程，因此你可以在确认更改前检查检测到的结构，并在之后撤销。因此，Pull 适合在另一台设备上继续工作、在编辑前检查仓库，或在浏览器存储被清除后恢复项目。它是导入，不是合并；如果当前项目和分支已经分叉，请仔细检查结果。

最重要的安全特性是：当你在编辑时远端分支发生移动，会发生什么。GB Coder 更新分支引用时禁用了 force。如果期间有人 Push，GitHub 会拒绝更新，面板会报告冲突，而不是悄悄丢弃对方的工作。解决方式刻意保持手动：把最新分支 Pull 到项目中，检查文件后再次 Push，或者转到桌面 Git 客户端进行真正的合并。其他失败会被区分，以便根据消息采取行动。失效令牌会产生认证错误并提示重新连接。速率限制会显示 GitHub 配额何时重置；API 对已认证用户允许每小时 5,000 次请求，而一次 Pull 每个文件消耗一次请求。仓库或分支不存在会产生 not-found 错误。请求在 60 秒后超时，长时间操作可以从面板取消。这些细节并不华丽，但它们决定了同步工具是值得信任，还是以模糊的方式失败。

令牌是高价值凭据。拥有写权限的 GitHub 令牌可以更改它能访问的每个仓库。默认情况下，GB Coder 把粘贴的令牌保存在模块作用域的 Map 中，这意味着关闭标签页后它就会消失，而且永远不会写入 localStorage。“Remember on this device”选项是明确的 opt-in。启用后，如果页面处于安全上下文，令牌在存储前会用 AES-GCM 和每次安装随机生成的密钥密封。这可以防止令牌以可读形式出现在浏览器配置文件备份、同步配置文件、共享机器、开发者工具截图或支持包中。它无法防止能在同一源上运行的脚本，因为这样的脚本可以调用同一个存储模块。任何纯浏览器设计都无法完全解决这一点。因此实际控制手段是范围、过期和撤销：使用限制在所需仓库的细粒度令牌，设置过期时间，并在工作完成后在 GitHub 上删除令牌。GitHub 流量从浏览器直接发往 api.github.com；LadeStack 不需要持有凭据。浏览器存储仍然不是备份，因此仓库也是合理的设备外副本。

GitHub 同步足以覆盖很大一部分浏览器项目：静态站点、React 或 Vue 原型、课堂练习、小型内部工具，或需要远端和部署来源的演示。它适合想在不安装 Git 的情况下进行版本管理的独立开发者、需要可复现交接的教师，以及在任何没有终端的机器上工作的人。它不足以应对包含子模块的 monorepo、依赖 Git LFS 的仓库、需要签名提交或详细审查提交历史的团队，或基于钩子和多远端的发布流程。那些是桌面 Git 的工作，假装不是只会让浏览器工作流更糟。有用的模式是混合式。先在浏览器中开始，因为首次预览是即时的。当项目形成值得保留的形态时 Push。当工作需要原生工具、更深入的调试器或完整 Git 工作流时，在桌面打开同一个仓库。回到浏览器时，通过 GitHub Pull 更改。文件是普通源文件，所以交接是版本控制，而不是迁移。要尝试浏览器这一半，打开 /app/projects 的 Projects Dashboard，创建项目，打开 GitHub sync，并 Push 第一次提交。完整设置和功能参考见文档。