用 Capgo 给 Capacitor 应用做免商店审核的…

当你想绕过应用商店审核、快速给 Capacitor 应用的 Web 层推送更新或热修复时使用。

适用场景

解决思路

1. 在 https://capgo.app 注册账号（可用 GitHub、Google 或邮箱），按需选择 Free/Solo/Team/Enterprise 套餐。
2. 全局安装 CLI：npm install -g @capgo/cli。
3. 登录：capgo login（会打开浏览器认证），或使用 API key：capgo login --apikey YOUR_API_KEY。
4. 在 Capacitor 项目目录执行 capgo init，它会创建 Capgo 应用、添加 @capgo/capacitor-updater 依赖、配置 capacitor.config.ts 并建立首个 channel。
5. 若插件未自动安装，手动执行 npm install @capgo/capacitor-updater 和 npx cap sync。
6. 在 capacitor.config.ts 的 plugins.CapacitorUpdater 中做基础配置：autoUpdate: true 开启自动更新。
7. 按需做高级配置：resetWhenUpdate、updateUrl、statsUrl、defaultChannel、periodCheckDelay、delayConditionsFail、privateKey 等。
8. 自动更新模式下，在应用启动 10 秒内调用 CapacitorUpdater.notifyAppReady()，否则 Capgo 会判定更新失败并回滚。
9. 手动更新模式：设 autoUpdate: false，然后用 CapacitorUpdater.getLatest() 检查更新、download() 下载 bundle、set() 设为下次启动生效、reload() 立即重载。
10. 需要用户确认时，用 @capacitor/dialog 的 Dialog.confirm 弹出更新提示，确认后再下载并 set + reload。
11. 监听更新事件：updateAvailable、downloadProgress、updateFailed、appReady。
12. 用 CLI 部署：先 npm run build，再 capgo upload；可加 --channel beta 指定渠道，或 --bundle 1.2.3 指定版本。
13. CI/CD 集成：GitHub Actions 中在 push 到 main 时执行 npm install、npm run build、npx @capgo/cli bundle upload，并通过 secrets 传入 CAPGO_TOKEN。
14. GitLab CI 中在 deploy 阶段用 node:20 镜像执行 npm install、npm run build、npx @capgo/cli bundle upload，仅对 main 分支触发，CAPGO_TOKEN 用变量传入。
15. 用 capgo channel create beta / staging 创建渠道，用 capgo upload --channel beta 部署到测试渠道，验证后再 --channel production 推到生产。
16. 灰度发布：在 Capgo 控制台 Channels > production 设置 rollout 百分比（如 10%），观察数据后逐步提升到 50%、100%。
17. 按设备分配渠道：用 CapacitorUpdater.setChannel({ channel: 'beta' }) 给测试用户，生产用户设为 production。
18. 自动回滚：若 10 秒内未调用 notifyAppReady()，Capgo 会自动回滚到上一个可用版本。
19. 手动回滚：capgo bundle list 查看版本，capgo bundle revert --bundle 1.2.2 --channel production 回滚指定版本。
20. 应用内回滚：用 CapacitorUpdater.list() 列出已下载 bundle，reset() 回到内置版本，delete({ id: 'bundle-id' }) 删除指定 bundle。
21. 自托管：docker run -d -p 8080:8080 -e DATABASE_URL=postgres://... capgo/capgo-server，并在 capacitor.config.ts 中把 updateUrl/statsUrl 指向自建服务器。
22. 加密更新：capgo key create 生成密钥对，capgo upload --key-v2 上传加密包，应用侧配置 privateKey。
23. 代码签名：capgo upload --sign 签名 bundle，capgo key verify 在应用内验证签名。
24. 在 Capgo 控制台监控活跃设备数、更新成功率、回滚率、版本分布和错误日志；也可用 CapacitorUpdater.current() 获取当前版本、getBuiltinVersion() 获取下载统计。
25. 排障：更新不生效时检查 notifyAppReady() 是否调用、app ID 是否匹配、channel 分配是否正确、查看控制台日志；出现回滚循环时确保 notifyAppReady() 尽早调用，必要时临时关闭更新调试；下载慢时启用 delta 更新、优化 bundle 体积或使用 CDN。
26. 最佳实践：启动后第一时间调用 notifyAppReady()；先在 beta 渠道测试；使用语义化版本号；监控回滚率；实现 error boundary；保持原生代码稳定（原生改动仍需走应用商店）。

适用边界 · 注意事项

• 需要修改原生代码（Swift/Kotlin/Java）时，仍必须提交应用商店审核，Capgo 无法绕过。
• 不想使用第三方付费服务或云厂商时（免费额度有限，Solo/Team 为付费套餐）。
• 无法接受把更新包和统计数据托管到外部服务器、又不愿自建 Capgo 服务时。