必须区分wgt热更新和APK/IPA整包更新：仅前端资源变更走wgt，涉及原生权限、插件、SDK、签名或监管要求等必须走整包；服务端需返回updateType字段明确类型，客户端据此分流，不可硬编码。
uni-app 的 App 内自动更新，必须区分「wgt 资源热更新」和「APK/IPA 整包更新」两种路径。混用或误判类型，90% 的失败都发生在这里——比如拿 wgt 包调 plus.runtime.install，或在 iOS 上强行走静默安装。
怎么判断该走 wgt 还是整包更新
wgt 只能更新 JS、CSS、模板、图片等前端资源；只要涉及以下任一变更，就必须走整包（APK/IPA）：
- manifest.json 中修改了原生权限、新增插件（如
uni-pay）、调整android.targetSdkVersion - iOS entitlements、后台模式、推送配置等原生能力变更
- 金融、政务类 App（监管强制要求整包，wgt 无法过审）
- Android 上新增了原生模块（如自定义 SDK），或签名不一致
服务端应返回明确字段，例如 updateType: "wgt" 或 "apk"，前端据此分流，而不是硬编码固定一种方式。
下载 wgt 包后为啥没生效
plus.runtime.install 对 wgt 是无效的——这是最常踩的坑。wgt 正确流程是：downloadFile → plus.runtime.reloadWgt → plus.runtime.restart。
- 下载必须用 HTTPS 直链，且服务器支持
Range请求（否则断点续传和差分校验失败） -
plus.runtime.reloadWgt只解压覆盖_www目录，不重启的话，当前 JS 上下文仍是旧资源，页面完全无变化 - 版本比对必须用
compareVersion(plus.runtime.version, serverData.version)，字符串比较（如"1.9.0" > "1.10.0"）会因字典序出错 - 服务端返回的
version字段必须规范：仅数字和点，禁止前导零（"1.05.0"❌）、字母（"v1.2.0"❌）、空格（"1.2.0 "❌）
Android 安装 APK 失败的三个硬性条件
不是代码写错了，而是运行时环境卡住了：
-
manifest.json中的versionCode必须是纯数字（如105），且严格大于当前已安装版本；写成"1.0.5"或105.0都会触发"Install failed: invalid version" - 下载路径必须是本地持久化路径，推荐
uni.env.USER_DATA_PATH + '/update/app-release.apk'；tempFilePath在华为/小米等 ROM 上几秒内就被回收 - Android 8.0+ 必须提前声明
android.permission.REQUEST_INSTALL_PACKAGES权限，并引导用户手动开启「允许安装未知来源应用」
iOS 上 uni.installApp 或 plus.runtime.install 不会安装 IPA，只跳转 App Store 或 TestFlight 页面——这不是 bug，是系统限制。
服务端返回 update: true 但客户端不触发下载
常见于字段名拼错、响应头不对、路径含非法字符：
- 确保服务端返回
Content-Type: application/json - JSON 字段名严格为
update、wgtUrl（wgt 场景）或pkgUrl（apk 场景），大小写敏感 -
wgtUrl或pkgUrl必须是 HTTPS 开头，路径不能含中文、空格、特殊符号（如https://example.com/资源包/UNIxxx.wgt❌） - 测试时直接用
curl请求接口，确认返回结构是否符合预期，避免被前端逻辑掩盖真实问题
真正难的不是写代码，而是每次发版前确认：manifest 版本号改对了没？HBuilderX 打的是 wgt 还是 apk？服务端字段和路径有没有一个字符偏差？这些地方一错，整个更新链就静默断裂。
