跳转到正文

一次性设置清单

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

规则: channels 是发布通道(development, production),而非工单、功能或开发者名称。


  1. 创建频道:选择最精简的组合(见下文)。

  2. 设置默认上传频道 中的 应用设置:

    • 单应用 → production
    • 团队 → development
  3. 生产频道: public 开启,device self-set 关闭,native 下阻止更新:开启,auto-update guard 开启 major.

  4. 测试频道 (development / staging):public 关闭,device self-set 开启以供 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

    本指南中介绍的 --bundle 值 必须 有效 语义化版本。请在 SemVer 测试器 在上传之前。

  6. 部署到生产环境 仅在测试后,从 仪表盘 或 CLI。

  7. 团队与安全: 只邀请一次,最小权限, 2FA 用于组织,在 CI 中使用一个 API 密钥。

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


选择你的规模

选择适合你的规模

基础:1 个应用,1 个通道: production

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

原生版本:仅在需要时添加通道,例如 production-9.0 + test-9.0。让商店用户停留在主生产通道。

多个应用:每个应用采用相同的简单模型(通常是一个 production 每个)。不要仅因为组织规模大就创建额外频道。

发布列车 (可选): staging → rc → production。所有需要它的应用都用同一个模板。


Bundle 名称与备注的区别

标题为“Bundle 名称与注释”的章节

Bundle 名称是 为必填项 需要遵循的 语义化版本. Capgo 使用 semver 进行兼容性检查、频道自动更新规则和回滚。请验证 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 中添加日期或 build 计数器: 1.8.0-20260629.1, 1.8.0-beta.2. 不要自创类似的自定义格式 fix-login-bug 或 2.5.2026062306. 它们不是有效的 semver,upload 会失败或行为不可预测。

将发布说明放在 --comment,而不是放在 bundle 名称里。

另请参阅 版本定向 以及 bundle 版本管理.


--delta 上传 增量文件 这样设备每次只需下载变更的文件,而非完整的 bundle。校验和始终自动计算,无需传入校验和标志。

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

标题为“默认:--delta(增量文件 + zip 备份)”的章节
终端窗口
npx @capgo/cli@latest bundle upload \
--channel development \
--bundle "1.8.0-${BUILD_NUMBER}" \
--delta

这是大多数应用的推荐默认设置。Capgo 存储增量文件 以及 保留完整的 zip 文件作为备份。运行旧版插件且不支持 Delta 的设备将使用 zip 文件。如果存储成本不是主要顾虑,这是不错的选择。

终端窗口
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 备份,你就完全依赖 delta 文件;而使用旧版插件、不支持 Delta 的设备将无法更新。跳过, --delta-only 除非你确实需要节省存储空间。

设备端无需额外的插件配置。updater 会读取 delta 文件列表,只拉取发生变化的文件。


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

错误修复
在新商店版本发布前预期 OTA 更新添加插件后重新构建并发布原生应用
上传了 bundle 但未部署到 channel将 bundle 分配给 channel(例如 production)
按功能、工单或开发者划分 channel仅使用永久发布通道
动态 CI channel 名称固定名称: development, production
简单应用使用了过多 channel从 1-2 个 channel 开始
设备在生产环境自行设置生产环境关闭,测试渠道开启
跳过 --delta添加 --delta 到上传;使用 --delta-only 仅在需要节省存储空间时
非 semver bundle 名称遵循 语义化版本 并在中验证 SemVer 测试器
随时间更改版本控制方案保持 semver;使用预发布标签进行额外构建(1.8.0-20260629.1)
未说明原因即启用元数据/预览默认关闭
全新安装时显示“有新版本可用”提示在以下情况跳过 current() 返回 bundle.id === "builtin" (见下文)

App Store 审核:全新安装时不会显示更新提示

章节标题:“App Store 审核:全新安装时不显示更新提示”

Apple 接受使用 Capgo 的应用。但审核员会拒绝其周围的 UI:首次启动时显示的“有新版本可用”或“正在更新”提示。

这主要影响自托管和手动配置,因为您的应用会自行执行版本检查并显示自己的提示。

审核员安装的是您的商店二进制文件。它比您最新的 bundle 旧,因此首次检查会立即发现 bundle:您的服务器调用返回它,或更新器找到它并触发 updateAvailable。如果您的应用此时显示消息,审核员就会看到。

在全新安装或原生商店更新后,应用会运行随包发布的 bundle,并且 current() 返回 bundle.id === "builtin"。这种情况下,请跳过你的消息:

import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()
if (bundle.id !== 'builtin') {
showNewVersionMessage()
}

在任何可见的 UI 中,避免使用“更新”、“live update”、“OTA”、“下载中”和“安装中”这些词。参见 合规性.