跳转到正文

常见更新问题

GitHub

当更新检查失败时,Capgo 通常会返回一个 error code 和一个 message ,详见 /updates 响应。本页介绍最常见的失败情况和最快的修复方法。

  • no_new_version_available 属于正常状态,并非失败。
  • 许多“发现更新但未应用”的报告其实是策略/配置拒绝,而不是缓存延迟,尤其是当响应中包含明确的 error code。
  • 使用 npx @capgo/cli@latest app debug 复现问题时查看请求/响应详情。

原因

应用已启用 拦截提供商基础设施请求 功能,且请求源自已知的 Google 或 Apple 数据中心 IP 段。Capgo 会在 /updates, /stats,以及 /channel_self 以防止来自服务商的流量被误判为设备流量。

修复

  • 请在普通用户网络环境下,使用真机复现更新过程。
  • 启用此保护时,请勿使用云端探测器或服务商数据中心运行器进行 updater、stats 或 channel-self 检查。
  • 如果该流量是预期的,请打开应用的 信息 选项卡并关闭 拦截提供商基础设施请求。测试完成后请重新开启。

新应用默认启用此保护。在引入该设置之前创建的应用将保持禁用状态,直到你手动开启。

响应详情

  • /updates 保持了 updater 的响应契约并返回 HTTP 200。其响应体包含 error, message, kind: "blocked",以及 provider ("google" 或 "apple").
  • /stats 以及 /channel_self 返回 HTTP 429 ,并附带相同的错误 code。请将其视为有意为之的策略拦截,而非可重试的瞬时故障。

原因

您的渠道禁止主要版本升级(disable_auto_update = major),且目标 bundle 的主要版本号高于设备基线版本。

典型症状

version: 1.0.8 配合 old: 0.0.0 表示设备上报的基线 0.0.0,因此大版本升级会被拒绝。

如何解读

后端使用设备基线比较主版本 old 和目标 version.

  • 如果目标是 1.0.1,基线主版本必须是 1 (例如 1.0.0).
  • 如果目标是 10.0.1,基线主版本必须是 10 (例如 10.0.0).

修复方案 A(推荐):对齐设备基线主版本

设置 plugins.CapacitorUpdater.version 中的 capacitor.config.* 因此,它 大版本 与您想要发布的 bundle MAJOR 版本匹配(例如 1.0.0 来实现 1.0.1, 10.0.0 来实现 10.0.1).

然后,将此配置一次性应用到已安装的应用:

  1. 运行 npx cap sync.
  2. 重新构建并重新安装原生应用。

修复方案 B:放宽 channel 策略

在渠道设置中允许跨主版本自动更新(仅当该发布策略是有意为之时)。

相关文档:

disable_auto_update_to_minor / disable_auto_update_to_patch

章节标题:“disable_auto_update_to_minor / disable_auto_update_to_patch”

原因

Channel 策略比正在提供的更新更严格(minor 或 patch)。

  • minor 当目标 bundle 的主版本或次版本与设备原生基线不同时,会拦截(version_build)。示例: 1.2.3 -> 1.3.0 会被拦截。
  • patch 会拦截从以下版本开始的任何主版本、次版本或补丁号变更: version_build。仅允许更改后缀,而 MAJOR.MINOR.PATCH 保持不变,例如 1.0.0-beta.1 -> 1.0.0-beta.2 或 1.0.0+build.1 -> 1.0.0+build.2.

修复

  • 上传与当前策略兼容的 bundle,或者
  • 在 dashboard/CLI 中更改 channel 策略。

相关文档:

原因

Channel 使用基于 metadata 的定向 (version_number) 且设备 baseline 低于要求的 min_update_version.

修复

  • 将设备基线 (CapacitorUpdater.version) 与已安装的原生应用版本对齐,或
  • 调整 min_update_version / channel 策略。

相关文档:

原因

Channel 会阻止降级到原生基线以下。

修复

  • 上传版本大于或等于原生基线的 bundle,或
  • 禁用该频道的“低于原生版本”降级保护。

相关文档:

原因

所选/默认频道不允许设备自行分配。

修复

  • 使用启用了自行分配的其他频道,或者
  • 将频道设为公开 / 启用自行分配。

相关文档:

原因

设备基线版本缺失(unknown)或不是 有效的 semver.

修复

  • 设置 plugins.CapacitorUpdater.version 到 有效的 semver 例如 1.2.3.
  • 同步并重新构建原生应用。

相关文档:

原因

Updater 插件版本过旧,不满足当前后端要求。

修复

  • 升级 @capgo/capacitor-updater.
  • 运行 npx cap sync.
  • 重新构建并重新安装原生应用。

disabled_platform_ios / disabled_platform_android

标题为“disabled_platform_ios / disabled_platform_android”的章节

原因

该 Channel 已针对此平台禁用更新。

修复

  • 在 Channel 中启用平台切换。

disable_prod_build / disable_dev_build / disable_device / disable_emulator

标题为 “disable_prod_build / disable_dev_build / disable_device / disable_emulator” 的章节

原因

Channel 不允许当前的 build 类型或运行时目标。

修复

  • 对齐 Channel 选项(allow_prod, allow_dev, allow_device, allow_emulator)与您的测试目标。

原因

Bundle 加密密钥与设备密钥不一致。

修复

  • 在应用配置和 bundle 加密工作流中使用相同的加密密钥/公钥。

原因

未能为该设备解析出有效的 channel。

修复

  • 设置云端默认 channel,或者
  • 设置 defaultChannel 在测试构建中,或者
  • 为设备分配 channel 覆盖。

相关文档:

原因

后端返回 HTTP 429,并带有 on_premise_app这会在三种情况下发生:

  1. Capgo 中不存在该 App ID — 设备发送的 app_id 未注册,因此后端没有相关记录。
  2. App 被标记为本地部署 (on-premise) — App 虽然存在,但配置为自托管更新,因此 Capgo 云端接口拒绝提供服务。
  3. 组织套餐已取消 — 该 App 所属组织的订阅已失效。

常见错误

拼写错误出现在 plugins.CapacitorUpdater.appId (在 capacitor.config.ts) 或与 Capgo 仪表板中注册的应用 ID 不匹配。后端无法区分“未知应用”和“本地部署应用”,因此会返回相同的错误 code。

修复

  • 请检查 app_id 与 Capgo 仪表板中显示的内容完全一致(区分大小写)。
  • 如果应用尚未注册,请运行 npx @capgo/cli@latest app add.
  • 如果应用是有意进行本地部署的,请设置 plugins.CapacitorUpdater.updateUrl 为您的自托管更新端点,而不是 Capgo 云 URL。
  • 如果组织计划已过期,请续订或升级计划。
  1. 确认该构建的应用 ID 和通道是否正确。
  2. 确认 CapacitorUpdater.version 与已安装的原生应用版本匹配。
  3. 确认频道策略 (disable_auto_update) 与预期发布计划一致。
  4. 确认平台/构建目标开关已允许该设备。
  5. 运行 npx @capgo/cli@latest app debug 并查看后端错误 code。

如果你正在使用 常见更新问题 要规划原生插件工作,请将其与 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。