一次性设置清单

复制一条配置 prompt，包含安装步骤和该插件的完整 Markdown 指南。

设置已完成 onboarding. 现在配置 Capgo 一次即可. 此后，日常工作只需 上传 → 测试 → 部署.

规则： channel 是发布通道（development, production），而非 ticket、功能或开发者名称。

一次性设置清单

创建 channel: 选择最适合的一组配置（见下文）。
设置默认 upload channel 在应用设置:
- Solo 应用 → production
- 团队版 → development
生产环境 channel： public 开启，device self-set 关闭，native 开启时拦截更新，auto-update guard 开启 major.
测试环境 channel (development / staging): public 关闭，QA 环境 device self-set 开启。
通过 CI 进行 upload 带 --delta （校验和及 Native Build 依赖项均为自动处理）：
终端窗口
```
npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta
```
该 --bundle 值必须有效语义化版本 (SemVer)。请在 SemVer 测试工具中进行验证，然后再进行 upload。
部署到生产环境 仅在测试完成后，通过 dashboard 或 CLI。
团队与安全： 仅邀请一次，权限最小化， 2FA 应用于组织，在 CI 中使用一个 API 密钥。

保持加密、 min_update_version元数据和预览关闭除非你有明确理由。

选择你的规模

简单：1 个 App，1 个 channel： production

团队版: development + production。上传到 dev，部署到 prod。

原生版本：仅在需要时添加 channel，例如 production-9.0 + test-9.0。让应用商店用户留在主 production channel 上。

多个 App：每个 App 采用相同的简单模式（通常各一个 production ）。不要因为组织规模大就额外创建 channel。

发布列车 （可选）： staging → rc → production. 每个需要该模板的应用都应保持一致。

Bundle 名称与注释

Bundle 名称必须遵循语义化版本控制 (semver)。Capgo 使用 semver 进行兼容性检查、channel 自动更新规则及回滚。请验证以下所有名称： SemVer 测试器在 upload 前。

名称 = 来自 CI 的 semver，例如 1.8.0, 1.8.0-beta.1，或者 1.8.0-20260629.42
备注 = 供人工阅读的自由文本 → commit abc1234 run 28059070270

使用 semver 预发布 标签（即 -) 当你在同一个版本下发布多个 build 时 MAJOR.MINOR.PATCH。例如，保持 1.8.0 并在 pre-release 中添加日期或构建计数器： 1.8.0-20260629.1, 1.8.0-beta.2。不要发明像 fix-login-bug 或 2.5.2026062306这样的自定义格式。它们不符合 semver 规范，会导致 upload 失败或行为异常。

请将发布说明放在 --comment中，而不是 bundle 名称中。

另请参阅版本定向和 bundle 版本控制.

增量上传

--delta 上传 增量文件 这样设备每次只需下载变更的文件，而非完整的 bundle。校验和（Checksum）会自动计算，无需手动传递校验和参数。

默认值： `--delta` (增量文件 + zip 备份)

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

这是大多数 App 的推荐默认设置。Capgo 会存储增量文件和并保留完整的 zip 作为备份。对于尚未支持 Delta 功能的旧版插件设备，将使用该 zip。适用于对存储成本不敏感的场景。

节省存储空间： `--delta-only`

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta-only

使用 --delta-only 当你想要 减少 Capgo 存储占用时。系统仅存储增量文件（delta files）而非完整的 zip 包。对于大型应用或上传量大的场景，建议开启此选项以节省存储空间。

权衡：由于服务器不再保留 zip 备份，你将完全依赖增量文件；此外，若设备上的插件版本过旧且不支持 Delta 功能，则无法进行更新。跳过 --delta-only 除非你确实需要节省存储空间。

设备端无需进行额外的插件配置。更新程序会读取增量文件列表，并仅获取发生变化的文件。

日常工作流

Upload to development (--delta)
  → test
  → deploy to production
  → don't touch channel settings again

常见错误

错误	修复
在应用商店发布新版本前期望使用 OTA	添加插件后重新构建并发布 Native Build
仅上传 bundle 但未部署到 channel	将 bundle 分配给 channel (例如 `production`)
按功能、工单或开发者分配 channel	仅使用永久发布通道
使用动态 CI channel 名称	固定名称： `development`, `production`
对于简单应用，channel 过多	建议从 1-2 个 channel 开始
生产环境中的设备自设	生产环境关闭，测试 channel 开启
跳过 `--delta`	添加 `--delta` 用于上传；使用 `--delta-only` 仅在需要节省存储空间时使用
非 SemVer 规范的 bundle 名称	遵循语义化版本控制 (SemVer) 并在以下工具中进行验证 SemVer 测试器
随着时间推移更改版本方案	保持 SemVer；使用预发布标签进行额外构建 (`1.8.0-20260629.1`)
无故启用 Metadata / preview	默认关闭

了解更多

渠道默认值、优先级与路由。

增量更新为何以及如何使用 --delta。

CI/CD 自动化 upload 与部署。

Bundle 校验和、依赖项与元数据。

一次性设置清单