uni-app App端增量热更新版本自动校验回滚实现方法

# 增量热更新的校验与回滚：这几步做不对，用户就等着白屏吧 先抛结论：增量更新校验绝对不能只看 version_code，必须基于完整包 hash。这个坑踩过的人太多了。 很多人习惯把热更新当普通版本升级处理——拉一次接口、比一次 version_code，然后直接 `uni.reLaunch()`。结果呢？用户看到白屏、功能异常，却查不出原因。说到底，热更新本身不改变原生包的 `versionCode` 或 `versionName`，光靠服务端返回的 version_code，根本判断不了热更新包是否完整、是否已经生效。 那怎么做？ 服务端必须为每个热更新包提供一个 `file_md5` 字段（注意，统一用 md5 小写 32 位，别用 base64 或 sha256，后续比对容易出问题）。客户端下载后，用 `uni.getFileInfo` 获取本地文件真实 md5，和服务端的返回值严格比对。一旦校验失败，不能跳过、不能静默重试——必须触发回滚逻辑。 热更新包的路径建议固定为 `_doc/hotfix/` + `version_name`（比如 `_doc/hotfix/1.2.3.zip`）。这样每次更新覆盖相同版本号，避免重复下载堆积。  ## 回滚到上一个热更新版本，靠的是本地缓存 + manifest 记录 uni-app 本身没有内置热更新历史管理，所有回滚动作必须你自己主动存档。每次成功加载热更新包后，立刻把当前有效版本号写进 `uni.setStorageSync('last_valid_hotfix', '1.2.3')`，同时把旧包备份到 `_doc/hotfix/backup/` 目录下。 一旦校验失败或运行时报错——比如 `require is not defined`、`Cannot find module`——就说明当前热更新不可用。这时候系统会怎么自救？ 第一步，读取 `uni.getStorageSync('last_valid_hotfix')`，获取上一个可用版本号。第二步，拼出备份路径，比如 `_doc/hotfix/backup/1.2.2.zip`。第三步，用 `uni.getZipFile` 解压并替换当前 `_doc/hotfix/` 下的内容。最后，调用 `uni.reLaunch()` 重启应用，让新资源生效。 需要注意的是，iOS 上解压 zip 后，必须手动删除旧 js 文件再写入，否则可能出现缓存残留。 ## 强制回滚时，uni.reLaunch 的冷启动陷阱要避开 App 冷启动阶段（也就是 `onLaunch` 中）执行 `uni.reLaunch()`，部分安卓机型会卡死或白屏——因为热更新资源还没加载完成，`reLaunch` 会清空整个 JS 上下文，导致新页面找不到模块。 正确的做法是等 H5+ 环境就绪、且热更新资源已确认加载完毕后再触发。具体来说： - 必须包裹在 `plus.ready(() => { ... })` 内部 - 回滚前检查 `uni.getSystemInfoSync().platform === 'android'`，如果是 Android，额外加 300ms 延迟再 `reLaunch` - iOS 不支持 `reLaunch` 后立即刷新资源，可以改用 `location.reload(true)` 强制重新加载 webview - 回滚失败时，降级为 toast 提示 + 手动重启按钮，不要无限循环尝试 ## 服务端配合：热更新包必须带 rollback_flag 和 expired_at 客户端没法自己判断某个热更新是否应该被废弃，这个决策必须由服务端驱动。每次下发热更新包时，接口至少返回三个关键字段： - `rollback_flag: true`：表示该包已被标记为异常，客户端收到后应立即回滚并清除本地缓存 - `expired_at: '2026-06-18T12:00:00Z'`：过期时间，客户端启动时需校验，超时则自动丢弃并回滚 - `depends_on: '1.2.2'`：显式声明依赖的基线版本，若本地没有该基线，则拒绝加载，直接回滚到最近兼容版本 需要特别留意：`depends_on` 必须和 `manifest.json` 中的 `versionName` 格式完全一致。比如 `"1.2.2"` 就是 `"1.2.2"`，不能写成 `"v1.2.2"` 或 `"1.2.2-beta"`——否则比对失败，永远回滚。 真正的难点从来不在代码怎么写，而在于热更新和原生包的生命周期必须解耦。你永远不知道用户上次更新是半年前还是五分钟前，也不清楚他中间跳过了几个 hotfix。所以，所有校验、缓存、回滚动作，都要默认“当前状态不可信”，每次启动都从头验证一遍。这才是工程化应有的原则。