跳转至正文

2026 年 Cordova Hot Code Push 替代方案

cordova-hot-code-push 和 Cordova 版 CodePush 已停止维护。本文介绍一个仍在维护的 Cordova 热 code 推送替代方案,包含配置、迁移步骤和回滚。

Cordova 热 code 推送替代方案指南的 Cordova 标志插图

如果你正在找 Cordova 热 code 推送的替代方案,多半是因为 cordova-hot-code-push-plugin 以及 Microsoft 的 CodePush for Cordova 都已失效或停止维护。如今仍在维护的选择是 @capgo/cordova-updater,一款 Cordova 插件,为 Cordova Android 13+ 和 Cordova iOS 7+ 应用带来 Capgo 实时更新,支持通道、回滚和加密 bundle,无需先迁移到 Capacitor。

2026 年 Cordova 热更新现状

cordova-hot-code-push 已归档

本指南中介绍的 nordnet/cordova-hot-code-push 该仓库已在 GitHub 上归档。最后一次 code 变更是在 2018 年 9 月,而最后一次 npm 发布 cordova-hot-code-push-plugin 是 1.5.3。它专为当时的 Cordova 平台和基于文件的 WebView 加载方式设计。现代 Cordova Android 通过 https://localhost 路径处理器提供应用,而 Cordova iOS 使用 WKWebView 配合 app:// scheme。假设 file:// 加载的插件不符合该模型,且无人对其进行更新。

如果您从未更新 Cordova 平台,现有安装可能看似仍能正常工作。这正是陷阱所在:若不想冒更新机制失效的风险,就无法迁移到当前的 Cordova Android 或 Xcode。

Cordova 的 CodePush 已成过去

Microsoft 已将其归档 cordova-plugin-code-push,并在 2022 年停止了 App Center 中的 Cordova 支持。2025 年 3 月 31 日,包括 build、分发和 CodePush 在内的核心 App Center 服务也已停用。该插件原本与 App Center 中的 CodePush 服务通信,因此现在已没有后端可提供更新。即使你改为自托管 CodePush 服务器,仍然会依赖已归档的客户端插件。

Ionic Appflow 替代方案

cordova-plugin-ionic 将 Cordova 应用接入 Ionic Appflow 的实时更新。Ionic 已宣布 Appflow 将逐步停止服务,因此使用该服务的团队也在寻找替代方案。我们在以下指南中介绍了这条路径: Appflow 替代方案指南.

替代方案需要什么

在选择任何工具之前,请对照以下要求进行检查:

要求 为什么这很重要
兼容当前的 Cordova Android 和 iOS 应用商店要求强制升级平台:自 2026 年 4 月起,App Store 上传需使用 Xcode 26;Google Play 每年还会要求提升 Android target API 版本。
无需依赖 cordova-plugin-ionic-webview 该插件已过时,且与现代 scheme 处理器存在冲突
自动回滚 错误的 bundle 不应导致应用崩溃
通道 先在内测用户中验证,再全量发布
签名或加密的 bundle 防止通过网络下发的 code 被篡改
版本定向 切勿发送需要更新原生 shell 的 JavaScript
对 CI 友好的 CLI 发布在 pipeline 中只需一条命令
持续维护 看最近的 release,而不只是 star 数

Cordova 的 Capgo

@capgo/cordova-updater 使用与 API 相同的 JavaScript API @capgo/capacitor-updater 以及相同的 Capgo Cloud 后端。bundle、channel、统计和签名在 Cordova、Capacitor 和 Electron 客户端上的工作方式完全一致。

要求

  • Cordova CLI 12+
  • Cordova Android 13+(默认 https://localhost/ scheme)
  • Cordova iOS 7+(默认 app://localhost/ scheme)
  • cordova-plugin-ionic-webview 已移除

检查您的平台:

cordova platform ls

如有需要,请升级:

cordova platform rm android && cordova platform add android@latest
cordova platform rm ios && cordova platform add ios@latest

安装

在 Capgo(dashboard 或 CLI)中创建应用,然后用你的 App ID 添加插件:

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add com.example.app --name "My Cordova App"

cordova plugin add @capgo/cordova-updater --variable APP_ID=com.example.app
cordova prepare android ios

安装时还可以设置更多选项。这些是插件变量,所以请运行 cordova prepare 修改后运行:

cordova plugin add @capgo/cordova-updater \
  --variable APP_ID=com.example.app \
  --variable DEFAULT_CHANNEL=production \
  --variable AUTO_UPDATE=atBackground \
  --variable APP_READY_TIMEOUT=10000

AUTO_UPDATE 默认为 atBackground,它会在后台下载更新,并在应用下次进入后台时应用更新。其他模式还包括 atInstall, onLaunch 以及 off ,可实现完全手动控制。

告知插件应用已正常启动

这是唯一不能跳过的一行。调用 notifyAppReady() 在每次启动后 deviceready。如果新 bundle 未在 APP_READY_TIMEOUT 毫秒内调用它,插件会将其标记为失败,并回滚到上一个可用的 bundle。

document.addEventListener('deviceready', async () => {
  const { Updater } = cordova.plugins;
  await Updater.notifyAppReady();
}, false);

请在应用真正渲染完成后再调用,不要放在脚本最顶部,这样才能检测到启动时崩溃的 bundle。

手动更新流程

如果设置 AUTO_UPDATE=off,你就可以控制何时检查、下载和应用:

document.addEventListener('deviceready', async () => {
  const { Updater } = cordova.plugins;
  await Updater.notifyAppReady();

  const latest = await Updater.getLatest();
  if (latest.url && !latest.error) {
    const bundle = await Updater.download({
      url: latest.url,
      version: latest.version,
      checksum: latest.checksum,
    });
    // Applied on next background/restart
    await Updater.next({ id: bundle.id });
  }
});

TypeScript 类型随包提供:

import type { UpdaterPlugin } from '@capgo/cordova-updater';

declare const cordova: { plugins: { Updater: UpdaterPlugin } };

发布更新

构建你的 www 文件夹并上传:

bun run build
bunx @capgo/cli@latest bundle upload com.example.app --path ./www --channel production

把这段放进 CI,放在测试之后。这个 Live Updates 页面 在 dashboard 中显示渠道发布、统计数据和回滚。

从 cordova-hot-code-push 迁移

  1. 移除旧插件及其配置。 删除 cordova-hot-code-push-plugin, chcp 部分位于 config.xml,以及 cordova-hcp CLI 和 chcp.json / chcp.manifest 从你的 build 中生成。
  2. 移除 cordova-plugin-ionic-webview 如果存在,并测试应用能否在默认 Cordova WebView 上运行。
  3. 升级 Cordova 平台 至 Android 13+ 和 iOS 7+。
  4. 安装 @capgo/cordova-updater 并添加 notifyAppReady().
  5. 发布新的商店构建。 旧安装保留旧插件。只有新二进制文件包含 Capgo 更新器。
  6. 上传你的第一个 bundle 到测试通道,在设备上验证,然后推送到生产环境。

不从商店更新的用户会一直使用旧机制,直到他们完成更新。如果旧更新服务器仍然可用,请在过渡期间保持其在线;否则就要接受这些用户在安装新二进制文件前无法获得 OTA 更新。

从 Cordova 版 CodePush 迁移

  • 替换 codePush.sync() 调用 notifyAppReady() 以及自动模式或 getLatest / download / next 流程。
  • 用通道(DEFAULT_CHANNEL).
  • 替换 code-push release-cordova 配合 bunx @capgo/cli@latest bundle upload.
  • 移除 CodePushDeploymentKey 来自 config.xml.

如需面向 App Center 用户的分步指南,请参阅 App Center 迁移指南.

安全与应用商店规则

  • 加密与签名。 设置 PUBLIC_KEY 在安装时执行,并使用 CLI 的加密密钥,确保设备仅接受为您应用签名的 bundle。
  • Apple 和 Google 的政策。 只要不改变应用用途,也不添加需要审核的功能,两者都允许通过 OTA 更新 JavaScript 等解释型 code。但 Native code、新插件和权限变更需要走应用商店发布。
  • 版本定向 如果某个 bundle 需要仅存在于较新二进制文件中的原生插件,请将其定向到该原生版本。关于 Capgo 的文档中, live update 兼容性 说明了具体做法。

故障排除

Bundle 已下载,但应用仍显示旧版本。 你仍在使用 cordova-plugin-ionic-webview,或自定义 scheme。请移除它并使用默认值。

应用每次更新后都会回滚。 notifyAppReady() 未被调用,或在报错后才被调用。请检查设备上的控制台,并确认每次启动时都会执行该调用。

平台升级后 iOS 构建失败。 Cordova iOS 7+ 需要最新版本的 Xcode。上传到 App Store 需要 Xcode 26。您可以使用 iOS 证书生成器生成签名资源。一旦迁移到 Capacitor, Capgo 构建 可以在云端生成已签名的 iOS 构建,无需本地 Mac。

更新在 Android 上有效,但在 iOS 上无效。 检查 config.xml 中的 iOS scheme app 是否为带有 localhost 主机名的默认 scheme。

你是否应该改用 Capacitor?

不必。Capgo 专为 Cordova 设计,让您在决策期间继续发布。Capacitor 提供受维护的原生层、iOS 上的 Swift Package Manager 以及更丰富的插件生态系统。当您准备好时,保留相同的 Capgo 应用 ID 和通道,只需替换客户端插件即可。我们的 Cordova 到 Capacitor 迁移指南 将逐步介绍此过程。

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。