capgo-live-updates

Capgo 实时更新

将 @capgo/capacitor-updater 接入 Capacitor 应用，发布第一个 bundle，并确保回滚安全。

以下信息已根据 @capgo/capacitor-updater 8.52 和 @capgo/cli 8.77 核实（2026 年 10 月）。

适用场景

在以下情况使用：

• 用户希望在 Capacitor 应用中使用 OTA／实时更新、无需经过应用商店审核即可发布热修复，或提到“Capgo”。
• 需要安装、升级或在 capacitor.config.* 中配置更新插件。
• 用户询问 notifyAppReady、autoUpdate 模式、directUpdate、autoSplashscreen、setChannel、getLatest、download、next、set 或 reset。
• 更新上传成功，但设备始终收不到更新、发生回滚或陷入循环。

以下情况不要使用：

• 工作仅涉及 CLI bundle、频道、发布范围或加密密钥命令。请使用 capgo-release-management。
• 用户需要由 Capgo Cloud 生成已签名的 IPA/APK/AAB。请使用 capgo-native-builds。
• 用户正在从 Capawesome Cloud（capawesome-live-update-migration）或 Ionic Appflow（ionic-appflow-migration）迁移。请使用相应工具。
• 用户需要完整的发布流水线（OTA、原生构建和应用商店发布）。请使用 capgo-release-workflows。
• 请求涉及通用 CLI 路由或 MCP 设置。请使用 capgo-cli-usage。

参考索引

仅在涉及某个主题时加载相应参考资料。

文件	加载时机
references/configuration.md	编辑 capacitor.config.* 中的 plugins.CapacitorUpdater、选择 autoUpdate 模式、配置自托管 URL
references/js-api.md	编写手动更新流程、监听器、频道切换或回滚代码
references/channels-and-rollouts.md	配置频道、设备自助分配、渐进式发布、版本定向
references/ci-cd.md	从 GitHub Actions、GitLab CI 或其他 CI 上传
references/troubleshooting.md	设备未更新、发生回滚或后端返回错误代码

版本规则（先阅读）

更新插件的主版本与 Capacitor 主版本一致。

Capacitor	安装命令
8.x	npm install @capgo/capacitor-updater@latest（8.x 系列）
7.x	npm install @capgo/capacitor-updater@lts-v7
6.x	npm install @capgo/capacitor-updater@lts-v6
5.x	npm install @capgo/capacitor-updater@lts-v5
4.x	npm install @capgo/capacitor-updater@lts-v4

Capacitor 9 注意事项：Capacitor 9 仍处于预发布阶段（@capacitor/core@next）。截至 2026 年 10 月，还没有适用于 Capacitor 9 的更新插件系列。8.x 系列声明了 peerDependencies: @capacitor/core ^8.0.0。npm 上的 @capgo/[email protected] 是 2023 年发布、适用于 Capacitor 5 的旧版本，已标记为弃用，因此切勿将其安装到 Capacitor 9 项目中。就 Capacitor 9 项目提供建议前，请使用 npm view @capgo/capacitor-updater dist-tags 检查当前标签。如果未列出 Capacitor 9 系列，请告知用户。

密钥与确认

• 切勿要求用户在聊天中粘贴 Capgo API 密钥、签名密码、.p8 密钥、密钥库或服务账号 JSON。请让他们自行运行 npx @capgo/cli@latest login（该命令会打开浏览器，或通过隐藏输入的提示要求输入密钥），或者在 shell 或 CI 密钥存储中设置 CAPGO_TOKEN。
• 不要将密钥放在命令参数中：它们会出现在 shell 历史记录和进程列表中。请使用环境变量、已保存的登录信息或 CLI 的交互式提示。
• 如果对话中出现了密钥，不要复述，也不要将其写入文件；请告知用户撤销该密钥并创建新密钥。
• npx @capgo/cli@latest 会从 npm 下载并运行最新 CLI。只有在用户项目中且获得用户同意后才能运行。在 CI 中，请固定到精确版本。
• 执行任何会更改远程状态的命令前都要先征求同意：上传 bundle、更改或提升频道、删除应用、bundle、频道或密钥、请求上传到应用商店的构建，以及导出或删除凭据。说明将对哪个应用和频道进行什么更改。

操作流程

1. 编辑前先检查

• 阅读 package.json，确认 @capacitor/core 的主版本，以及是否已有 @capgo/capacitor-updater。
• 阅读 capacitor.config.ts|json，确认 appId、webDir，以及是否已有 plugins.CapacitorUpdater。
• 找到应用入口文件（main.ts、main.tsx、App.vue setup、app.component.ts 等）。notifyAppReady() 应放在这里。
• 检查是否使用了其他 OTA SDK。如果有，请停止并切换到相应的迁移技能。

2. 连接项目（推荐方式）

引导式接入流程会注册应用、安装插件、修改入口文件、构建、上传并在设备上验证：

npx @capgo/cli@latest init

请用户在终端中运行此命令：它会通过浏览器登录（或使用 login 保存的密钥），询问应用 ID，并上传首个 bundle，因此请先征得用户同意。不要在聊天中索要 API 密钥。在 monorepo 中，添加 --package-json、--main-file 和 --capacitor-config。

3. 手动安装（不使用 init 时）

npm install @capgo/capacitor-updater@latest   # pick the tag from the Version Rule table
npx cap sync
npx @capgo/cli@latest app add com.example.app

最低限度的配置（autoUpdate 默认为 true，等同于 "atBackground"）：

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

4. 立即调用 notifyAppReady()

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

CapacitorUpdater.notifyAppReady();

• 在入口文件最开头调用它，在任何网络请求或异步初始化之前。如果未在 appReadyTimeout（默认 10000 ms）内调用，bundle 会被标记为失败，并恢复到上一个版本。
• 调用后发生的崩溃或 API 错误不会触发回滚。
• bundle upload 会检查是否调用了此函数；如果未调用，则会报错 notifyAppReady() is missing in the build folder (...)。请修复源代码。只有在用户接受回滚风险时，才使用 --ignore-notify-app-ready / --no-code-check。

5. 发布 bundle

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 配合设置。请参阅 references/configuration.md。

6. 每次发布前决定使用 OTA 还是原生构建

OTA 只能更改 Web 资源。新增或升级原生插件、升级 Capacitor，或修改 ios/、android/ 下的内容或原生配置，都需要通过应用商店构建。请使用以下命令检查：

npx @capgo/cli@latest bundle releaseType com.example.app --channel production   # prints OTA or native

releaseType 只比较原生包元数据，无法检测 ios/ 或 android/ 下的直接修改。

易踩问题

• **应用商店合规：**OTA 只能更改解释型 Web 代码和资源，且不得改变应用的主要用途。这项要求来自 Apple Developer Program License Agreement 中关于解释型代码的条款、App Review Guideline 2.5.2，以及 Google Play 的 Device and Network Abuse 政策。切勿使用 OTA 发布需要审核的功能，也不要强制更新来阻止用户使用应用。
• **隐私清单：**iOS 需要在 PrivacyInfo.xcprivacy 中添加 NSPrivacyAccessedAPICategoryUserDefaults，并指定原因 CA92.1。
• **配置键是 publicKey，不是 privateKey。**私钥（.capgo_key_v2）应仅由上传工具持有，绝不可放在应用或仓库中。
• **resetWhenUpdate（默认 true）**会在安装新的原生构建时清除已下载的 bundle。如果禁用此选项，应用商店构建的版本低于 OTA bundle 时可能会导致问题。
• **在开发构建版本上测试：**渠道可能会通过标志（disable_dev_build、disable_emulator 等）阻止开发设备、模拟器或生产设备。认定插件有问题之前，请先检查渠道选项。
• **实时重载（Ionic/Quasar）：**更新器不会提供实时重载 URL。测试更新时，请关闭实时重载。
• **set() 会销毁 JS 上下文。**它后面的代码都不会执行。建议使用 next()，在下一次后台运行时应用更新。
• **加密不等于保密：**未加密的 bundle 是公开的 Web 资源。加密可以保护存储和传输，但公钥会随应用一起发布。请参阅 capgo-release-management 中的 key create / key save。

验证

1. npx @capgo/cli@latest doctor 会显示已安装的更新器版本，并标记任何过时的内容。
2. grep -rn "notifyAppReady" src/ 会在入口点找到且仅找到一次提前调用。
3. npx cap sync 成功后，在真实设备上构建并安装一次原生应用。
4. 上传一个有明显变化的 bundle。在后台运行并重新打开应用时，运行 npx @capgo/cli@latest app debug com.example.app。日志应显示检查、下载和 set。
5. npx @capgo/cli@latest probe --platform ios（或 android）会报告后端是否会向此配置推送更新，并说明原因。

错误处理

症状 / 字符串	修复方法
notifyAppReady() is missing in the build folder	在入口点添加调用，重新构建，然后再次上传
index.html is missing in the root folder of <dir>	--path 指向了错误的文件夹。请使用构建后的 webDir
no_new_version_available	正常：设备已是最新版本
disable_auto_update_to_major / _minor / _patch	通道策略阻止了此次升级。调整 CapacitorUpdater.version 或更改 --disable-auto-update
cannot_update_via_private_channel	在通道上启用自分配（channel set <ch> --self-assign）
on_premise_app（HTTP 429）	appId 不在 Capgo 中、应用被标记为本地部署，或方案已取消
更新下载后在下次启动时还原	notifyAppReady() 执行得太晚或未执行，或者 bundle 在调用前抛出异常

完整代码列表见 references/troubleshooting.md。

资源

• 入门指南：https://capgo.app/docs/getting-started/add-an-app/
• 插件设置：https://capgo.app/docs/plugins/updater/settings/
• 插件 API：https://capgo.app/docs/plugins/updater/api/
• 更新行为：https://capgo.app/docs/live-updates/update-behavior/
• 常见问题：https://capgo.app/docs/plugins/updater/commonproblems/