wgt热更新不可手动切换降级或跳变，必须严格遵循versionCode纯数字递增、原生配置零变更、SDK版本锁定三原则；plus.runtime.install强制校验versionCode，force:true仅跳过校验但风险极高。
不能靠“手动切换”来解决增量热更新的版本兼容性问题——wgt 包本身不支持运行时动态降级或跨版本跳变，所谓“切换”只是掩盖了底层校验逻辑失效的风险。
plus.runtime.install 的 versionCode 校验不可绕过
uni-app 的热更新依赖 plus.runtime.install，它在 Android/iOS 上均强制比对 manifest.json 中的 versionCode（纯数字）与当前 App 内嵌值：
- 设
force: false（默认）：新包versionCode≤ 当前值 → 直接进 error 回调，错误信息固定为"Install failed: invalid version"，不暴露具体数值 - 设
force: true：跳过校验，但会覆盖安装——若新 wgt 基于旧版 SDK 编译，或含未声明的原生能力（如新增android.permission.FOREGROUND_SERVICE），App 启动后大概率白屏或闪退，且无法回滚 -
versionName（如"2.1.0"）仅作展示用，plus.runtime.install完全不读取它；字符串比较（如"2.1.0" > "2.0.9"）在 iOS 侧可能因类型转换失败而跳过检测
真正可控的“兼容性控制点”在服务端返回逻辑
客户端没有自由选择“用哪个 wgt”的权限，能干预的只有是否发起安装。所谓“手动切换”，实际应转化为服务端按设备特征返回适配包：
- 请求升级接口时，必须带上
platform、versionCode、uni-app compiler version（可从uni.getProvider或预埋常量获取） - 服务端根据这些字段查表匹配：同一逻辑版本号（如 105）可能对应多个 wgt 包，分别适配
compiler 3.4.13和3.5.2，避免插件 ABI 不兼容 - 返回结构中明确带
mustForce: false或mustForce: true字段，客户端据此决定传入force参数——仅当服务端确认该 wgt 已通过对应环境测试时才允许force: true - 禁止前端自行解析
versionName做跳转逻辑，比如 “用户点了 v2.1.0 就去拉 v2.1.0.wgt” —— 这会导致versionCode断层（如 v2.1.0 对应 105，v2.0.9 却是 104），触发静默失败
wgt 包生成时路径和 manifest.json 必须平级
本地打包 wgt 若出错，后续所有“切换”动作都无效——因为 plus.runtime.install 读取的是包内根目录下的 manifest.json，不是子路径里的：
- 正确流程：
yarn build:app-plus→ 进入dist/build/app-plus/→ 确认该目录下存在manifest.json且versionCode已更新 → 执行zip -r app.wgt . -x "*.DS_Store" - 常见错误：HBuilderX “制作 wgt 包” 默认输出到
unpackage/dist/build/app-plus/，但 zip 时误选父目录，导致解压后第一行为unpackage/dist/build/app-plus/manifest.json→ 安装时找不到根 manifest，静默失败 - 验证方式：上传前执行
unzip -l app.wgt | head -n 1，输出必须是manifest.json，而非任何带路径的变体
真正的兼容性保障不在前端“怎么切”，而在每次 wgt 构建时是否严格遵循 versionCode 递增、原生配置零变更、SDK 版本锁定这三条铁律；一旦破坏，所谓手动切换只会把问题延迟到用户启动那一刻。
