uni-app怎么做App端自动检查更新 uni-app热更新wgt包流程教程
作者：袖梨
2026-07-07
onLaunch 中调用 plus.runtime.getProperty 是唯一可靠入口，必须传 plus.runtime.appid 获取 version 和 versionCode；更新逻辑需后端驱动，versionCode 须转整数比对，Android 11+ 需 REQUEST_INSTALL_PACKAGES 权限，安装失败多因签名、versionCode 或路径权限问题。
onLaunch 里调用 plus.runtime.getProperty 是唯一可靠入口
App 启动后第一时间读取本地版本信息，是所有更新逻辑的前提。不能依赖页面 mounted 或 onLoad —— 用户可能跳过登录页、从后台唤醒、甚至没进任何 Vue 页面，onLaunch 是 uni-app 中唯一能保证执行的全局生命周期钩子。
-
plus.runtime.getProperty必须传plus.runtime.appid，否则拿不到当前包的version和versionCode - 别在 request 成功回调里直接写安装逻辑 —— 网络延迟或超时会导致用户长时间无反馈，应先缓存版本数据再发请求
- Android 11+ 上，如果没提前申请
REQUEST_INSTALL_PACKAGES权限，plus.runtime.install会静默失败，控制台也不报错
uni.request 请求更新接口必须带 versionCode 做精准比对
服务端不能只返回“有更新”，而要根据客户端传来的 versionCode 返回可更新的 wgt 地址。很多团队用字符串比版本（如 "1.0.0" > "1.0.10"），结果 1.0.10 被判成更小 —— 这是因为字符串比较按字典序，不是数值序。
- 务必把
versionCode当整数处理：用parseInt(widgetInfo.versionCode)转换后再传给后端 - 后端返回字段建议统一为
update: true、wgtUrl、isForce: boolean，避免前端再解析语义 - 测试时故意把本地
versionCode改小（比如改 100），看是否真触发下载；别只靠日志判断“进了 success 回调”就认为 OK
plus.runtime.install 安装失败的三大隐形原因
下载成功但安装失败，90% 不是代码问题，而是环境或配置卡点。控制台不报错、fail 回调里的 e.message 常为空，得靠排除法定位。
- 签名不一致：wgt 包必须和原安装包使用同一份证书签名，HBuilderX 打包时「自定义基座」和「云打包」签名不同，混用必失败
- 版本未递增：manifest.json 里
versionCode没变，或变小了，plus.runtime.install会直接拒绝（iOS 更严格） - 路径权限问题：Android 10+ 要求
tempFilePath必须在应用私有目录（uni.getEnvInfo().plusRuntimePath下），不能用uni.downloadFile默认的公共 Download 目录
静默更新 + 强制更新的边界必须由后端驱动
前端无法自己决定“要不要强制”。所谓“强制更新”，本质是后端返回 isForce: true 且该版本 versionCode 高于当前所有可选版本。前端只做两件事：展示弹窗、调用安装。
- 不要在前端硬编码“versionCode > 105 就强制”，版本策略必须收口到后端，否则热更新变成“半吊子整包更新”
- 用户取消强制更新后，下次启动仍要检查 —— 不能靠本地 flag 记录“已忽略”，否则新版本来了也收不到
- 静默更新（比如资源替换、JS 修复）可以跳过弹窗，但必须确保
plus.runtime.install成功后调用plus.runtime.restart()，否则新资源不生效
