应根据修改内容判断:仅更新js、vue页面及静态资源可走wgt热更新;若修改manifest.json权限、新增原生插件、升级cli或runtime等原生层变更,则必须整包更新。

怎么判断该走 wgt 热更新还是整包更新
增量热更新(wgt)只适用于 JS、Vue 页面、静态资源(如图片、CSS)的替换,改不了原生层。一旦你动了以下任意一项,wgt 就失效,必须走整包更新:manifest.json 里的权限声明、插件配置、pages.json 的原生 tabbar 图标路径以外的结构、新增 native 插件(比如微信登录)、CLI 升级或底层 runtime 变更。很多团队误以为“代码发版=热更新”,结果用户打开白屏——因为 plus.runtime.version 对应的运行时环境没变,新 wgt 里调用了旧 runtime 不支持的 API。
版本号比对必须语义化,不能字符串直接比较
"1.9.0" > "1.10.0" 在字典序下为 true,但实际是旧版。服务端返回的 version 字段必须清洗后分段转数字比对。推荐用 HBuilderX 3.1.22+ 内置的 uni.compareVersion(a, b),或手写清洗逻辑:remoteVer.replace(/^v|[^0-9.]/g, ''),再按点分割、补零、逐位比对。注意:本地版本必须取自 plus.runtime.getProperty(plus.runtime.appid, cb) 返回的 widgetInfo.version,它对应 manifest.json 中填的 versionName,打包即固化,不受热更新影响。
wgt 下载后不生效?四个关键断点
wgt 更新不是“下载完成就完事”,它要经历下载 → 校验(MD5/签名)→ 替换资源 → 重启 WebView 四步。常见卡点:
- 服务端
update.json返回 404 或响应头缺失Content-Type: application/json,onCheckForUpdate不报错,但onUpdateReady永远不触发 -
update.json中的packageUrl指向的 wgt 文件未开启 CORS,iOS WKWebView 会静默失败 - 下载路径未用 HTTPS,安卓某些版本拦截非安全源
- 用户正在操作页面(如输入中、动画进行时),
applyUpdate()被系统延迟或拒绝——建议在onHide后延时 300ms 再调用,避开操作高峰
Android 8+ 和 iOS 的静默限制必须绕开
Android 8+(API 26)起,plus.runtime.install() 默认被系统拦截,报错 INSTALL_FAILED_USER_RESTRICTED。这不是代码问题,是权限限制。必须提前在 manifest.json → 模块配置 → Native.js 权限中勾选 android.permission.REQUEST_INSTALL_PACKAGES,并在首次启动时调用 plus.android.requestPermissions 获取授权。iOS 则根本无法静默安装 wgt,它只允许替换资源并 reload WebView,且资源写入位置受限(NSCachesDirectory),重启后仍有效——但若用户清缓存,已下载的 wgt 会丢失,onUpdateReady 触发后 applyUpdate 可能失败。
plus.ready 就绪后再获取版本号,否则 plus.runtime.getProperty 返回空或报错;还有,开发环境务必用 process.env.NODE_ENV === 'development' 跳过检查,避免调试时反复弹窗干扰。











