uni-app APP 高效热更新全攻略

一. 背景

随着 App 成功上架，可能更新频率往往会越来越高。传统的应用更新方式要求用户重新下载并安装应用，这不仅耗费用户大量时间、流量，还严重影响用户体验。为了提升用户体验，热更新技术应运而生，为用户带来了更加便捷高效的更新体验。

二. 什么是热更新？

uni-app 热更新是一项强大的技术，无需重新安装应用，就能动态更新应用的内容。它可以在应用持续运行的状态下，对功能、样式以及各类资源进行升级，显著提升用户体验，大幅缩短用户等待时间，同时有效降低应用安装与更新的成本。

简而言之，uni-app APP 有两种更新方式：

整包升级：将整个应用更新至最新版本，属于全量更新。其优势在于更新全面，速度较快；不过缺点也很明显，更新完成后用户需要重新安装应用。
wgt 资源升级：仅将应用的资源更新到最新版本，属于增量更新。这种方式的好处是更新速度快，对用户影响小；但存在一定的局限性，并非适用于所有类型的更新。

uni-app 热更新的实现流程如下：

在应用中添加热更新功能。
将更新的内容打包成 wgt 资源包。
将 wgt 资源包上传到服务器。
应用在启动时，检查是否有更新。
如果有更新，应用会下载 wgt 资源包，并安装到应用中。
应用重新启动，更新的内容就会生效。

三. 生成 wgt

1. 前提条件

已在 HBuilderX 中创建好应用，并且已经编译打包成功。
已经配置好应用的应用 ID（appid）。
已经配置好应用的版本号（version）。

等等具备了一系列应用上架的前提条件，不再赘述。

2. 修改版本号

首先，需要更新 manifest.json 中的版本号。比如之前是 1.0.0，那么新版本应该是 1.0.1 或 1.1.0。要大于现有的版本号。

3. 打包 wgt 包

在 HBuilderX 中打包升级包（wgt）

点击菜单->发行->App-制作应用 wgt 包

打包结束会在控制台输出 wgt 升级包的具体位置

四. 安装 wgt

安装应用资源升级包（wgt）通常需要服务端与客户端配合完成，下面以本地测试过程中的操作举例说明：

1. 服务端

上传资源：

将上面生成的 wgt 文件存放在服务器的目录下，例如完整的示例文件地址为： http://www.example.com/files/DEMO_APP_202504210407.wgt

提供检测更新接口：

需约定用于检测升级的接口，示例接口地址为：http://www.example.com/api/checkVersion

注意：服务端的具体判定逻辑，需根据自身业务需求灵活调整。

该部分内容不做重点讲述！

2. 客户端

客户端需要在合适的场景下主动检测升级，如果发现有新版的 wgt 资源包，需要下载到本地进行安装，一般在应用启动的时候检测一次即可。

在 App.vue 的 onLaunch 中进行检测升级，代码如下：

js 复制代码

// #ifdef APP-PLUS
plus.runtime.getProperty(plus.runtime.appid, function (widgetInfo) {
  uni.request({
    url: 'http://www.example.com/api/checkVersion',
    data: {
      version: widgetInfo.version,
      name: widgetInfo.name
    },
    success: result => {
      const data = result.data
      if (data.update && data.wgtUrl) {
        uni.downloadFile({
          url: data.wgtUrl,
          success: downloadResult => {
            if (downloadResult.statusCode === 200) {
              plus.runtime.install(
                downloadResult.tempFilePath,
                {
                  force: false
                },
                function () {
                  // 下载资源成功，重启应用
                  plus.runtime.restart()
                },
                function (e) {
                  // 下载资源失败
                }
              )
            }
          }
        })
      }
    }
  })
})
// #endif

这段代码主要实现了：

获取应用信息 ：借助 plus.runtime.getProperty 方法，获取当前应用的信息，像版本号、应用名称这类信息会存储在 widgetInfo 对象里。
发起版本检测请求 ：使用 uni.request 方法向服务端的 http://www.example.com/api/checkVersion 接口发送请求，请求数据包含当前应用的版本号和名称。
处理服务端响应 ：当请求成功后，检查服务端返回的数据。若 data.update 为 true 且 data.wgtUrl 存在，就意味着有新的更新包。
下载更新包 ：利用 uni.downloadFile 方法下载服务端提供的 wgt 资源包。
安装更新包 ：若下载成功（状态码为 200），则调用 plus.runtime.install 方法安装下载好的 wgt 资源包。
处理安装结果：安装成功时，并重启应用；安装失败时，需要提示或进行其他相关策略。

注意：代码逻辑仅做了核心演示，实际情况下可以加入错误处理 ，比如在 uni.request 和 uni.downloadFile 里添加错误处理逻辑，从而更好地捕获和处理请求与下载过程中出现的错误。

五. 注意事项

平台限制：使用条件编译，确保升级逻辑仅在 App 平台执行。
版本获取 ：plus.runtime.version 或 uni.getSystemInfo() 读取的是 apk/ipa 包版本号，而非 manifest.json 中的资源版本信息。因此，建议使用 plus.runtime.getProperty() 来获取准确的应用信息。
安装重启 ：安装 wgt 资源包成功后，务必调用 plus.runtime.restart()，否则更新内容将无法生效。
兼容性测试：若仅升级 wgt 包而不更新 App 原生引擎，需特别注意测试 wgt 资源与原生基座的兼容性。平台默认会对版本不匹配的情况进行提醒，如下图所示：

如果自测没问题，可以在 manifest 中配置忽略提示：

json 复制代码

//...
"app-plus": {
    "compatible": {
        "ignoreVersion": true //true表示忽略版本检查提示框，HBuilderX1.9.0及以上版本支持
    },
//....
}

六. 热更新不支持的情况

当 SDK 部分进行调整，例如新增 Maps 模块时，无法通过热更新方式升级，必须采用整包升级。
若对原生插件进行增加或修改，同样不能使用热更新方式。
若原有项目中没有 nvue 文件，而更新内容包含新增 nvue 文件，也不适用热更新方式。

七. 热更新是否影响应用审核

应用市场出于防止开发者未经审核向用户提供违法内容的考虑，大多对热更新持谨慎态度。

然而，热更新在实际开发中应用广泛，无论是原生开发还是跨平台开发领域皆是如此。

Apple 曾封禁过 jspatch，但并未对其他热更新方案如 Cordova、React Native、DCloud 进行打击。封禁 jspatch 主要是因其存在严重安全漏洞，可能被黑客利用来篡改其他 App 的数据。

使用热更新时，需注意以下几点：

在上架审核期间，切勿弹出热更新提示。
采用 HTTPS 协议下载热更新内容，防止被第三方网络劫持。
避免更新违法内容，也不要通过热更新损害应用市场的利益，例如 iOS 的虚拟支付，此类情况需按规定向 Apple 分成。

只要遵循这些规则，应用使用热更新通常不会出现问题。