必须等plus.ready就绪后再获取plus.runtime.version并检查更新，避免空值或报错；版本比较须用数值语义逐段比对，禁用字符串直接比较；Android 8+需申请REQUEST_INSTALL_PACKAGES权限方可静默安装。
plus.ready 未就绪就调用 runtime.version 会返回空或报错
App 启动时直接在 onLaunch 里读 plus.runtime.version，大概率拿到空字符串或 undefined，尤其在冷启动、低端安卓机上。这是因为 H5+ 环境还没初始化完。
必须等 plus.ready 回调触发后再执行版本检查逻辑：
plus.ready(() => {
const currentVersion = plus.runtime.version
// 此处再发起 check-update 请求
})
开发环境建议加判断跳过：
-
process.env.NODE_ENV === 'development'时直接 return，避免反复弹窗干扰调试 - 如果首页有登录态或网络依赖，把检查逻辑挪到
onShow或路由守卫中更稳妥
compareVersion 比较字符串版本号会出错
"1.9.0" !== "1.10.0" 返回 true，但字典序比较结果是 "1.9.0" > "1.10.0"，导致误判为“无需更新”。不能用 === 或 !== 直接比对。
必须用数值语义逐段比对：
- 推荐使用 uni-app 社区验证过的
uni.compareVersion(a, b)（HBuilderX 3.1.22+ 内置） - 若项目未升级，可手写简易版：
["1","9","0"].map(Number)转数组后逐位比对 - 服务端返回的
version字段必须规范：纯数字点分格式（如"1.10.0"），禁用"v1.10.0"、"1.10.0-beta"、前导零等
Android 8+ 安装 APK 报 INSTALL_FAILED_USER_RESTRICTED
从 Android 8（API 26）起，plus.runtime.install() 默认被系统拦截，错误信息就是 INSTALL_FAILED_USER_RESTRICTED。这不是代码问题，是系统权限限制。
要静默安装，必须提前申请 REQUEST_INSTALL_PACKAGES 权限：
- manifest.json → 模块配置 → 勾选「Native.js 权限」→ 找到并启用
android.permission.REQUEST_INSTALL_PACKAGES - 首次安装前需主动调用
plus.android.requestPermissions(['android.permission.REQUEST_INSTALL_PACKAGES']) - 若用户拒绝，应跳转至设置页引导开启，而不是卡死或静默失败
- 下载路径建议用
_doc/update.apk，避免写入外部存储被拦截
plus.downloader.createDownload 状态监听不触发
常见现象：调用 createDownload 后没进 statechanged 回调，或只触发一次 start 就停住。根本原因往往不在逻辑，而在环境配置。
重点排查这几项：
- URL 必须是
https直链，不能是短链、跳转链接或带重定向的地址 - 证书必须有效，自签名证书在部分安卓机型上会静默失败
- 下载路径参数必须合法，例如
_doc/update.apk，不能写成/sdcard/xxx.apk - 务必监听
statechanged和error两个回调，仅靠完成回调不够——比如网络中断时可能永远不触发完成
复杂点在于：热更新（wgt）和整包更新（apk）共存时，服务端需明确返回 wgtUrl 或 pkgUrl，客户端根据平台和策略选择分支；iOS 只能走 App Store，无法静默安装，这部分逻辑容易被忽略。
