capgo-live-updates

用途

Capgo Live Updates 用于在 Capacitor 应用中接入并调试基于 @capgo/capacitor-updater 的热更新（OTA）能力。它面向希望在不经过应用商店审核的情况下发布 Web 层修复的场景，涵盖插件安装、首个更新包发布以及回滚安全保障。

将 @capgo/capacitor-updater 插件接入 Capacitor 项目，完成安装与配置。
引导完成首个更新包（bundle）的构建与上传。
处理 notifyAppReady、autoUpdate 模式、directUpdate、autoSplashscreen、setChannel、getLatest、download、next、set、reset 等相关 API 与配置。
排查“更新上传成功但设备收不到”“回滚”“循环更新”等问题。
通过 npx @capgo/cli@latest probe 等命令验证后端是否会向当前配置下发更新。

技能提供两种接入路径。首选是引导式初始化，注册应用、安装插件、修补入口文件、构建、上传并在设备上验证：

npx @capgo/cli@latest init YOUR_API_KEY com.example.app

API 密钥位于 https://console.capgo.app/dashboard/apikeys。若用户已提供密钥，直接使用且不要回显。在 monorepo 中可添加 --package-json、--main-file 和 --capacitor-config。

手动安装方式：

npm install @capgo/capacitor-updater@latest
npx cap sync
npx @capgo/cli@latest app add com.example.app

最小配置（autoUpdate 默认为 true，等同于 "atBackground"）：

plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
  },
},

入口文件顶部需立即调用 notifyAppReady()：

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.notifyAppReady();

发布更新包：

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production

对于即时生效模式（"atInstall"、"onLaunch"、"always"），需使用 --delta 上传，并设置 autoSplashscreen: true 与 @capacitor/splash-screen launchAutoHide: false。

每次发布前用以下命令判断是走 OTA 还是原生构建：

npx @capgo/cli@latest bundle releaseType com.example.app --channel production

版本规则：更新器主版本跟随 Capacitor 主版本。Capacitor 8.x 使用 @capgo/capacitor-updater@latest；7.x 使用 @lts-v7，依此类推。Capacitor 9 截至 2026 年 10 月尚无对应更新器版本，npm 上的 @capgo/capacitor-updater@9.0.0 是 2023 年的旧 Capacitor 5 版本且已弃用，切勿安装。
OTA 只能修改 Web 资源。新增或升级原生插件、升级 Capacitor 或修改 ios/、android/ 目录及原生配置，需要商店构建。
商店合规：OTA 只能修改解释型 Web 代码与资源，且不得改变应用主要用途。不得用 OTA 发布需要审核的功能，也不得强制更新以阻止应用使用。
iOS 需要在 PrivacyInfo.xcprivacy 中声明 NSPrivacyAccessedAPICategoryUserDefaults，理由为 CA92.1。
配置键为 publicKey，而非 privateKey；私钥（.capgo_key_v2）应保留在上传端，绝不能放入应用或仓库。
resetWhenUpdate 默认为 true。禁用后，早于 OTA 包的商店构建可能出问题。
开发构建测试时，渠道可能通过标记（disable_dev_build、disable_emulator 等）屏蔽开发、模拟器或生产设备。
实时重载（Ionic/Quasar）：更新器不提供实时重载 URL，测试更新时应关闭实时重载。
set() 会销毁 JS 上下文，其后的代码不会执行，建议用 next() 在下次进入后台时应用。
加密不等于保密：未加密的包是公开 Web 资源，加密保护存储与传输，但公钥随应用一同分发。

npx @capgo/cli@latest doctor 显示已安装的更新器版本并标记过时项。
grep -rn "notifyAppReady" src/ 应找到入口点中唯一一处早期调用。
常见错误包括：notifyAppReady() is missing（需在入口点添加调用后重新构建）、index.html is missing（--path 指向错误文件夹）、no_new_version_available（设备已最新，属正常）、cannot_update_via_private_channel（需在渠道启用 self-assign）、on_premise_app（HTTP 429，appId 不在 Capgo 或计划被取消）等。
更新下载后在下次启动时还原，通常是 notifyAppReady() 执行过晚或未执行，或包在其运行前抛出异常。