uni.getupdatemanager触发wgt热更新需满足三条件:非调试模式、manifest.json的versionname与update.json的version语义化可比、资源https+支持cors;版本须逐段数字比对,下载后须在onupdateready中调用applyupdate并plus.runtime.restart重启。

怎么用 uni.getUpdateManager 触发 wgt 差异包下载
直接调 uni.getUpdateManager() 就能走热更新流程,但它只在 App 端生效,且必须满足三个硬条件:非调试模式、manifest.json 中的 versionName 与远程 update.json 的 version 字段语义化可比、资源路径支持 HTTPS + CORS。
常见错误是开发时开着调试模式跑,结果 onCheckForUpdate 根本不触发——它静默失效,也不报错。上线前务必确认 HBuilderX 打包时「运行环境」选的是「发行」而非「调试」。
-
update.json必须放在 HTTPS 域名下,响应头含Content-Type: application/json -
update.json里的packageUrl指向的 .wgt 包也得是 HTTPS,iOS WKWebView 对 HTTP 资源会静默拦截 - Android 和 iOS 都支持,但 iOS 下 wgt 解压后写入
NSCachesDirectory,重启后仍有效;Android 若用户清缓存,已下载的 wgt 可能丢失,onUpdateReady触发后applyUpdate可能失败
为什么 manifest.json 和 update.json 版本号必须严格对齐
不是“只要数字大就行”,而是语义化版本(如 "1.2.3")必须逐段比较:1.2.3 → [1,2,3],1.10.0 → [1,10,0]。字符串比对 "1.10.0" > "1.2.0" 返回 false 是最典型翻车点。
服务端返回的 version 字段如果带前缀(v1.2.3)或后缀(1.2.3-beta),前端必须清洗再分段转 Number 比对,否则 update.version > manifest.versionName 判断必然出错。
- 清洗建议:
remoteVer.replace(/^v|[^0-9.]/g, '') - 比对函数要补零对齐,比如
"1.2"应转为[1,2,0],再逐位比较 - manifest.json 中的
versionName是打包固化值,不能靠uni.getSystemInfoSync().version读取——它在 iOS 上可能为空,在 Android 上可能含前缀,且热更新后会变
下载 wgt 后怎么安全安装并重启
wgt 安装不是“下载完就自动生效”,必须显式调用 updateManager.applyUpdate(),且该操作只能在 onUpdateReady 回调里执行。提前调或在别处调,会静默失败。
安装后需主动重启,plus.runtime.restart() 是唯一可靠方式;uni.reLaunch() 或 uni.navigateTo() 都不行——它们只刷新 WebView,不重载 wgt 资源。
- iOS 上重启后 wgt 生效,但原生层代码(如 SDK 初始化)不会重执行,仅 JS/CSS/HTML 生效
- Android 若 wgt 包里新增了原生插件(如 share 配置),会导致 iOS 安装失败——实测过,iOS 对 wgt 内 manifest 结构更敏感,必须和原 APK 的
manifest.json结构完全一致(除了 versionName) - 下载过程中若网络中断,
onUpdateFailed会触发,但不会自动重试,需自行加 fallback 逻辑(比如降级到整包更新链接)
增量更新失败时怎么优雅降级到整包更新
热更新只是锦上添花,不能当唯一依赖。wgt 下载超时、解析失败、applyUpdate 报错,都应导向整包更新入口——比如弹窗提供「稍后手动更新」按钮,跳转至 APK/IPA 下载页或 App Store。
关键点在于:不要等 wgt 流程彻底失败才行动。可在 onCheckForUpdate 后加个 10 秒超时计时器,一旦 onUpdateReady 未触发,就切换为整包检查逻辑。
- 整包更新接口和热更新接口最好分开,避免共用同一字段造成语义混淆
- Android 下整包下载路径必须用
uni.env.USER_DATA_PATH或uni.env.TEMP_FILE_PATH,拼/sdcard/xxx.apk在 Android 10+ 会静默失败 - iOS 无法静默安装 IPA,只能跳转
itms-services://?action=download-manifest&url=xxx.plist,而 plist 必须由企业证书签名且托管在 HTTPS 域名下











