更新记录

1.0.4（2026-04-27）

• 继续优化

1.0.3（2026-04-27）

• 更新了说明文档

1.0.2（2026-04-27）

• 优化体验感

平台兼容性

uni-app(4.25)

uni-app x(4.25)

fl-appUpgrade

fl-appUpgrade 是一个面向 uni-app / uni-app x App 端的 UTS 升级插件，提供 Android / iOS 原生升级弹框、APK 下载进度、wgt 资源更新回调，以及 App Store / 应用市场跳转能力。

插件适用于以下场景：

• 需要统一管理 Android / iOS 版本升级入口
• 需要同时支持整包升级与 wgt 资源更新
• 需要区分强制更新与可取消更新策略
• 需要以 uni_modules 形式复用升级能力

功能特性

• 支持 Android / iOS 原生升级弹框
• 支持 Android APK 下载进度展示与安装拉起
• 支持 wgt 下载完成回调，便于接入 plus.runtime.install
• 支持 iOS App Store 跳转
• 支持 Android 应用市场包名或 Scheme 跳转
• 支持强制更新、可取消更新、后台下载等升级策略
• 支持 classic、hero、spotlight、minimal 四套弹窗模板
• 支持头图、角标、按钮文案和主题配色自定义

支持平台

支持：

• Android App
• iOS App
• uni-app Vue2
• uni-app Vue3
• uni-app x

不支持：

• H5
• 各类小程序平台

说明：

• Web 和小程序端不会执行原生升级逻辑
• 插件包含 Android Kotlin 与 iOS Swift 的原生实现，建议在自定义调试基座或正式包中验证
• 当前工程按 uni-app / uni-app x 4.25+ 场景设计，开发时建议使用较新的 HBuilderX

安装与引入

将插件安装到项目 uni_modules 目录后，在页面或业务模块中引入：

import {
  startUpgrade,
  closeUpgradeDialog,
  installApk,
  openMarket
} from "@/uni_modules/fl-appUpgrade"

API

startUpgrade(options)

统一升级入口。

参数说明

模式说明

• apk：Android 整包升级，适用于 APK 下载与安装
• wgt：资源更新，下载完成后通过事件回调交由业务侧安装
• store：商店升级，适用于 iOS App Store 或 Android 应用市场跳转

模板说明

• classic：传统升级卡片，适合常规业务场景
• hero：大头图样式，适合品牌化升级提示
• spotlight：强调型样式，适合强更或大版本发布
• minimal：极简样式，适合轻提示或内部应用

closeUpgradeDialog()

手动关闭升级弹框。

说明：

• 可取消更新场景下可正常关闭
• 强制更新下载进行中会拦截关闭行为，并触发 blocked-close 事件
• Android 弹框展示期间会拦截系统返回关闭

installApk(options)

Android 单独拉起 APK 安装页。

installApk({
  filePath: "/storage/emulated/0/Android/data/xxx/files/Download/app-release.apk"
})

openMarket(options)

跳转应用市场。

openMarket({
  androidPackageName: "com.example.app",
  androidMarketPackage: "com.huawei.appmarket",
  iosStoreUrl: "https://apps.apple.com/cn/app/id1234567890"
})

事件说明

onEvent 回调中可能出现以下事件：

事件对象结构：

type UpgradeEvent = {
  type: string
  progress?: number
  filePath?: string
  errCode?: number
  errMsg?: string
  message?: string
}

主题配置

theme 支持以下可选字段：

• backgroundColor：弹框背景色
• titleColor：标题文字色
• contentColor：内容文字色
• primaryColor：主按钮背景色
• updateButtonTextColor：主按钮文字色
• cancelTextColor：Android “进入后台”按钮文字色
• secondaryButtonBackgroundColor：次按钮背景色
• secondaryButtonTextColor：次按钮文字色
• badgeBackgroundColor：角标背景色
• badgeTextColor：角标文字色
• progressTrackColor：进度条轨道色
• progressTextColor：进度文案色

使用示例

Android 整包升级

startUpgrade({
  mode: "apk",
  template: "hero",
  heroImage: "https://example.com/path/to/upgrade-banner.jpg",
  heroImageHeight: 168,
  content: "1. 修复已知问题\n2. 优化启动速度\n3. 提升稳定性",
  downloadUrl: "https://example.com/path/to/app-release.apk",
  version: "1.2.3",
  force: false,
  autoInstallApk: true,
  theme: {
    backgroundColor: "#FFFFFF",
    titleColor: "#111111",
    contentColor: "#5E6472",
    primaryColor: "#1677FF",
    updateButtonTextColor: "#FFFFFF",
    secondaryButtonBackgroundColor: "#EEF2F7",
    secondaryButtonTextColor: "#667085",
    cancelTextColor: "#667085",
    badgeBackgroundColor: "#1677FF",
    badgeTextColor: "#FFFFFF",
    progressTrackColor: "#E5E7EB",
    progressTextColor: "#5E6472"
  },
  onEvent(e) {
    console.log("upgrade event", e)
  },
  fail(err) {
    console.error("upgrade fail", err)
  },
  complete(res) {
    console.log("upgrade complete", res)
  }
})

Android 强制更新

startUpgrade({
  mode: "apk",
  title: "需要升级后继续使用",
  content: "当前版本已停止支持，请立即升级到最新版本",
  downloadUrl: "https://example.com/path/to/app-release.apk",
  version: "1.2.3",
  force: true,
  showBackgroundButton: false
})

强制更新场景下：

• 不显示取消按钮
• Android 返回关闭会被拦截
• 下载中调用 closeUpgradeDialog() 会被拦截

wgt 资源更新

startUpgrade({
  mode: "wgt",
  title: "资源更新",
  content: "检测到资源包更新，点击立即升级",
  downloadUrl: "https://example.com/path/to/update.wgt",
  version: "1.2.3-20260424",
  onEvent(e) {
    if (e.type === "downloaded" && e.filePath) {
      plus.runtime.install(
        e.filePath,
        { force: false },
        () => {
          plus.runtime.restart()
        },
        (err) => {
          console.error("wgt install failed", err)
        }
      )
    }
  }
})

iOS App Store 升级

startUpgrade({
  mode: "store",
  title: "发现新版本",
  content: "请前往 App Store 完成升级",
  downloadUrl: "https://apps.apple.com/cn/app/id1234567890",
  storeSchemeUrl: "https://apps.apple.com/cn/app/id1234567890"
})

推荐版本策略

建议服务端至少返回以下字段：

• latestVersion：最新整包版本
• minVersion：最低支持整包版本
• wgtVersion：最新资源版本

推荐策略：

• 当前整包版本 < minVersion：强制整包升级
• minVersion <= 当前整包版本 < latestVersion：提示可取消整包升级
• 当前整包版本 == latestVersion && 当前 wgt 版本 < wgtVersion：提示资源更新

平台差异

Android

• 整包升级通过系统下载管理器实现
• 下载完成后可自动拉起 APK 安装
• 应用市场跳转优先使用传入的市场包名或 Scheme
• APK 安装依赖插件内置 FileProvider

iOS

• iOS 整包升级本质上是跳转 App Store
• iOS 不支持应用内静默安装 IPA
• wgt 模式只负责下载并回调文件路径，安装逻辑需业务侧接入

接入注意事项

• wgt 仅更新前端资源，不会更新插件自身的 UTS / Kotlin / Swift 原生代码
• 标准调试基座下，部分原生配置和三方能力可能不会生效
• 真实升级能力请在自定义调试基座或正式包中验证
• store 模式下建议同时提供 downloadUrl 与 storeSchemeUrl，避免不同设备跳转差异

常见问题

为什么标准基座下调用没有效果

插件包含原生代码与原生配置，需使用自定义调试基座或正式打包环境验证。

为什么 iOS 不能直接安装 IPA

由于 iOS 平台限制，应用无法自行安装整包，整包升级应跳转 App Store。