一次性设置清单
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
你已完成 onboarding。现在配置 Capgo 一次。之后,日常工作只需 上传 → 测试 → 部署.
规则: channels 是发布通道(development, production),而非工单、功能或开发者名称。
一次性设置清单
“一次性设置清单”章节-
创建频道:选择最精简的组合(见下文)。
-
设置默认上传频道 中的 应用设置:
- 单应用 →
production - 团队 →
development
- 单应用 →
-
生产频道: public 开启,device self-set 关闭,native 下阻止更新:开启,auto-update guard 开启
major. -
测试频道 (
development/staging):public 关闭,device self-set 开启以供 QA 使用。 -
从 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 测试器 在上传之前。 -
部署到生产环境 仅在测试后,从 仪表盘 或 CLI。
-
团队与安全: 只邀请一次,最小权限, 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 文件。如果存储成本不是主要顾虑,这是不错的选择。
节省存储空间: --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 备份,你就完全依赖 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”、“下载中”和“安装中”这些词。参见 合规性.