跳过内容
Capgo - Capacitor应用的实时更新 Capgo

一次性设置清单

你完成了 onboarding. 现在配置 Capgo 一次。 之后，日常工作只有 上传 → 测试 → 部署.

规则： 渠道是发布分支（），而不是工单、功能或开发人员名称。development, production一次性设置清单

一次性设置清单

创建渠道

  1. 选择最小的集合（见下文）。设置默认上传渠道

  2. 在 应用设置 Solo应用→:

    • 团队→ production
    • 生产渠道： development

  3. channels are release lanes ("), not tickets, features, or developer names. 公网开启，设备自设关闭，原生开启下，更新阻断开启，自动更新守卫开启 major.

  4. 测试频道 (development / staging): 公网关闭，设备自设开启用于QA.

  5. 从CI上传 与 --delta （校验和原生依赖是自动的）：

    终端窗口
    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

    The --bundle 值 必须 有效 语义版本控制. 在 SemVer 测试器 在上传之前验证它。

  6. 仅在测试后才部署到生产环境 从 或 __CAPGO_KEEP_0__。 or CLI.

  7. 一次邀请，权限最少 2FA 为组织设置，CI 中仅有一把 __CAPGO_KEEP_0__ 密钥 for the org, one API key in CI.

离开加密， min_update_version, 元数据和预览 关闭 除非你有明确的理由。

选择你的大小

标题：选择你的大小

简单: 1 个应用，1 个频道： production

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

原生版本: 只在需要时添加频道，例如 production-9.0 + test-9.0. 保持商店用户在主生产频道。

许多应用: 每个应用通常有一个相同的简单模型。 production 每个应用都有一个。

不要仅仅因为组织很大就创建多个频道。 发布列车 staging → rc → production(可选):

不要使用以门票、人员或 CI 变量命名的频道，如

Bundle 名称与注释

包名必须遵循 是必需的 遵循 语义版本. Capgo 使用 semver 进行兼容性检查、自动更新规则和回滚。 在上传前，验证每个包名在 SemVer 测试器 中。

  • 名称 = 从 CI 中获取的语义版本，例如 1.8.0, 1.8.0-beta.1，或 1.8.0-20260629.42
  • 评论 = 为人类准备的自由文本 → commit abc1234 run 28059070270

使用 semver 预发布 标签（当您在同一个版本下发布多个构建时，标签的部分） -例如，保留 MAJOR.MINOR.PATCH并在预发布中添加日期或构建计数： 1.8.0 不要 invent 自定义格式，如 1.8.0-20260629.1, 1.8.0-beta.2或 fix-login-bug or 2.5.2026062306. They are not valid semver and uploads will fail or behave unpredictably.

Put release notes in --comment, not in the bundle name.

See also __CAPGO_KEEP_0__ 和 __CAPGO_KEEP_1__.

__CAPGO_KEEP_2__

Delta 上传

--delta 上传一个 清单 因此设备每次下载只下载更改的文件，而不是整个包。校验和始终自动计算。您不需要传递校验和标志。

默认： --delta (清单 + zip 备份)

终端窗口
__CAPGO_KEEP_3__
npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

对于大多数应用程序来说，这是推荐的默认设置。Capgo存储了清单 并 保留完整的zip文件作为备份。 当存储成本不是主要关注点时，很好。

存储节省: --delta-only

存储节省：--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/清单文件，而不是完整的zip文件。 选择此选项时，应考虑到存储成本较高的应用程序或高上传量的情况。

权衡: 在没有服务器 zip 备份的情况下,您完全依赖于 manifest 路径. 跳过 --delta-only 除非您实际上需要存储节省.

不需要在设备上额外配置插件. 更新器读取 manifest 并只下载更改的文件.

日常工作流程

复制到剪贴板
Upload to development (--delta)
  → test
  → deploy to production
  → don't touch channel settings again

常见错误

常见错误
错误修复
在新商店发布前期望OTA在添加插件后重建并发布原生应用
上传包但未部署到渠道将包分配到渠道（例如 production)
按特性、工单或开发者分配渠道只使用永久发布通道
动态CI渠道名称固定名称： development, production
一个简单应用程序的通道太多了从1-2个通道开始
设备自设为生产环境生产环境关闭，测试通道开启
跳过 --delta添加 --delta 添加到上传列表中；在需要节省存储空间时使用 --delta-only 非语义版本号的包名
遵循语义版本号 并在 __CAPGO_KEEP_0__ SemVer测试器
版本号方案的变化保持 SemVer; 使用预发布标签进行额外构建（1.8.0-20260629.1)
元数据/预览功能未经理由启用默认不启用

了解更多

了解更多
频道 默认值、优先级和路由
增量更新 为什么和如何使用 --delta。
CI/CD 自动上传和部署。
包装 校验和、依赖项和元数据。