更新记录

2.2.0（2026-05-17）

添加鸿蒙支持

2.1.3（2026-05-17）

修复bug

平台兼容性

uni-app(3.7.7)

ly028-updater

App 版本升级 UTS 插件：整包 APK / wgt 热更新弹窗、下载进度、强制更新、多主题 UI、Android 国内应用市场跳转、iOS App Store 跳转。

平台支持

• 环境：HBuilderX 3.7.2+（鸿蒙建议 4.31+），uni-app Vue2/Vue3，仅 App / 鸿蒙 真机
• 调试：需 自定义调试基座 或正式云打包（UTS 插件）
• 鸿蒙：需使用 运行到鸿蒙；downloadUrl 为应用市场链接时跳转华为应用市场（与 iOS 类似）

快速开始

1. 安装

方式一：插件市场试用（推荐，UTS 源码不可见）

在 DCloud 插件市场 打开本插件 详情页，按顺序操作：

1. 导入示例工程
   点击 「使用 HBuilderX 导入示例项目」，选择本地目录，将示例工程导入到本机（导入后 HBuilderX 会自动打开该项目）。

2. 申请试用并绑定项目
   回到插件 详情页，点击 「试用」（或「免费试用」）。
   在弹窗中选择 刚才导入到本地的示例项目（不要选错其他工程），确认后 HBuilderX 会将 加密试用版 插件安装到该项目的 uni_modules/ly028-updater（试用者看不到 UTS 明文源码）。

3. 配置 AppID
   在示例工程中打开 manifest.json → 基础配置 → 点击 重新获取 AppID（须登录 DCloud 账号），保存。

4. 制作自定义调试基座（必做）
   菜单 运行 → 运行到手机或模拟器 → 制作自定义调试基座，选择 Android 或 iOS，使用测试证书，等待云打包完成。
   UTS 插件必须编入基座，标准基座无法调试本插件。

5. 运行到真机（选择自定义基座）
   手机 USB 连接并开启调试 → 运行 → 运行到手机或模拟器 → 运行到 Android/iOS App 基座 → 选择 自定义调试基座（不要选标准基座）→ 等待安装启动。

6. 在示例首页测试
   点击「整包升级弹窗」「wgt 热更新」「智能升级」等按钮验证；iOS 真机可测「跳转 App Store」示例。

注意：请勿单独下载示例 zip 解压使用，也勿直接打开作者 Git 仓库中的 example/ 源码目录；请始终从 插件详情页 完成「导入示例 + 试用」流程。试用包仅可用于自定义基座调试，不可用于正式发布。

方式二：集成到已有项目

已购买或试用后，也可将 uni_modules/ly028-updater 复制到你项目的 uni_modules 目录，或在 HBuilderX 中从插件市场 导入插件 到当前项目。集成后同样需 制作自定义调试基座 再真机运行。

2. 挂载升级弹窗组件（重要）

uni-app 不会把 App.vue 里的 <template> 画到具体页面上，因此 <ly-updater /> 必须写在会显示升级的页面里（如首页、tab 首页），不能只写在 App.vue。

页面中挂载（必做）：

<template>
  <view>
    <ly-updater />
    <!-- 你的页面内容 -->
  </view>
</template>

App.vue 中初始化（推荐）：

import LyUpdater from '@/uni_modules/ly028-updater/js_sdk/index.js'

export default {
  onLaunch() {
    LyUpdater.init()
  }
}

也可在页面 onLoad 中调用 LyUpdater.init()（组件 mounted 时也会自动 init）。

组件支持 easycom，一般无需在 pages.json 手动注册。

3. 调用升级

import LyUpdater from '@/uni_modules/ly028-updater/js_sdk/index.js'

// Android 整包：downloadUrl 填 apk 直链
LyUpdater.startUpdate({
  title: '发现新版本',
  content: '1、修复已知问题；\n2、优化性能；',
  downloadUrl: 'https://cdn.example.com/app/latest.apk',
  versionCode: '1.0.2',
  theme: 'aurora',
  onClose: () => console.log('弹窗关闭')
})

// iOS 整包：downloadUrl 填 App Store 地址（见下文「iOS 整包更新」）
LyUpdater.startUpdate({
  title: '发现新版本',
  content: '请前往 App Store 更新',
  downloadUrl: 'https://apps.apple.com/cn/app/id1234567890'
})

// wgt 热更新（Android / iOS 相同：填 .wgt 资源地址）
LyUpdater.wgtUpdate({
  title: '资源更新',
  content: '请点击升级',
  downloadUrl: 'https://cdn.example.com/update.wgt'
})

HarmonyOS 整包更新（华为应用市场）

鸿蒙整包升级时，downloadUrl 可填 华为应用市场详情链接 或目标应用 bundleName（通过应用市场 URI 打开），例如：

store://appgallery.huawei.com/app/detail?id=com.your.app

也可在业务层直接调用 LyUpdater.startMarket({ pageName: 'com.your.app' }) 跳转应用市场。

wgt / hap 文件下载安装依赖 uni.downloadFile + 运行时安装能力，建议在 正式打包后的鸿蒙应用 上验证；HBuilderX 标准运行基座能力可能不完整。

iOS 整包更新（App Store 地址）

苹果不允许应用内直接安装 ipa，因此 iOS 整包升级时，downloadUrl 必须填写 App Store 链接，用户点击「立即升级」后会跳转到 App Store，不会下载安装包。

downloadUrl 填什么？

支持的 App Store 链接示例

任选一种可打开的商店地址即可：

https://apps.apple.com/cn/app/id1234567890
https://apps.apple.com/app/id1234567890
itms-apps://itunes.apple.com/app/id1234567890

其中 1234567890 为你在 App Store Connect 中的 Apple ID（数字），不是 Bundle ID。

代码示例

LyUpdater.startUpdate({
  title: '发现新版本',
  content: '请前往 App Store 完成更新',
  downloadUrl: 'https://apps.apple.com/cn/app/id你的AppleID',
  iosAppStoreOnly: true // 默认 true：iOS 只跳商店，不尝试下载
})

相关参数

成功回调

iOS 跳转商店后，onSuccess 可能收到：

{ type: 'ios_store' }

表示已唤起 App Store，不代表用户已完成更新。

注意

• 请勿将 apk 地址用于 iOS 整包。
• wgt 热更新不受此限制，downloadUrl 仍填服务器上的 .wgt 地址。
• 若需填写应用 Bundle ID 相关跳转，请使用完整 App Store URL（推荐在后台配置好链接后下发给客户端）。

推荐接入方式

// 推荐
import LyUpdater, { compareVersion, startMarket } from '@/uni_modules/ly028-updater/js_sdk/index.js'

// UTS 原生（仅 App，且需自定义基座）
import { getMarkets, getAppVersionNative } from '@/uni_modules/ly028-updater'

升级业务流程

服务端返回版本信息
       ↓
compareVersion / checkUpdate / smartUpdate 判断是否需要更新
       ↓
  ┌────┴────┐
整包更新   wgt 热更新
  ↓         ↓
startUpdate  wgtUpdate 显示弹窗
  ↓         ↓
用户点击「立即升级」
  ↓         ↓
下载 APK    下载 wgt → 安装 → 重启
  ↓
系统安装界面（Android）

版本号规则：本地 plus.runtime.version 为整包版本；wgt 版本通过 getLocalVersions() 异步获取。

// 手动判断示例
const local = await LyUpdater.getLocalVersions()
if (LyUpdater.compareVersion(local.appVersion, remote.appVersion) < 0) {
  LyUpdater.startUpdate({ ... })
} else if (LyUpdater.compareVersion(local.wgtVersion, remote.wgtVersion) < 0) {
  LyUpdater.wgtUpdate({ ... })
}

API 文档

一、LyUpdater 主对象

通过 import LyUpdater from '@/uni_modules/ly028-updater/js_sdk/index.js' 使用。

LyUpdater.init()

初始化事件监听，必须在 App.vue 的 onLaunch 中调用一次。

LyUpdater.startUpdate(options, onClose?)

显示 整包升级 弹窗。

LyUpdater.wgtUpdate(options, onClose?)

显示 wgt 热更新 弹窗。参数同 startUpdate，内部 updateType 为 wgt。

LyUpdater.close()

关闭升级弹窗；若正在下载会 中止下载任务。

LyUpdater.smartUpdate(remote)

根据远程版本 自动选择 整包或 wgt，需要更新时自动弹窗。

参数 remote：

返回值 Promise：

{
  updated: boolean,  // 是否已触发弹窗
  type: 'none' | 'app' | 'wgt',
  local: { appVersion, wgtVersion, ... },
  remote: { ... }
}

示例：

const ret = await LyUpdater.smartUpdate({
  appVersion: '2.0.0',
  wgtVersion: '2.0.1',
  appDownloadUrl: 'https://cdn.example.com/app.apk',
  wgtDownloadUrl: 'https://cdn.example.com/update.wgt',
  title: '发现新版本',
  content: '更新日志…'
})
if (!ret.updated) {
  uni.showToast({ title: '已是最新', icon: 'none' })
}

LyUpdater.getLocalVersions()

获取本地版本（App 端）。

返回 Promise：

LyUpdater.checkUpdate(remote)

仅判断是否需要更新，不弹窗。

参数同 smartUpdate 的版本字段；返回 { type: 'none'|'app'|'wgt', local, remote }。

LyUpdater.compareVersion(a, b)

版本号比较（纯 JS，全平台可用）。

• 返回 1：a > b
• 返回 0：相等
• 返回 -1：a < b

支持 1.0.10、v1.0.2 等格式。

LyUpdater.needAppUpdate(local, remote) / needWgtUpdate(local, remote)

是否需要整包 / wgt 更新的布尔值封装。

LyUpdater.getMarkets() 【Android】

返回本机已安装的应用市场列表。

[
  { key: 'huawei', packageName: 'com.huawei.appmarket', label: '华为应用市场' },
  ...
]

LyUpdater.startMarket(options) / startOtherMarket(options)

跳转指定 Android 应用市场中的应用详情页。

LyUpdater.startMarket({
  pageName: 'com.tencent.mm',
  marketPackageName: 'com.huawei.appmarket'
})

// 或使用 marketKey
LyUpdater.startOtherMarket({
  pageName: 'com.your.app',
  marketKey: 'huawei'
})

LyUpdater.openPreferredMarket(pageName) 【Android】

按 手机品牌 自动选择已安装市场并跳转。

LyUpdater.getPreferredMarketKey() 【Android】

返回当前机型推荐的市场 key，如 huawei、xiaomi。

LyUpdater.getAppVersionNative() 【App】

通过 UTS 原生读取安装包版本（不含 wgt 异步信息）。

常量

二、UpdateOptions 弹窗配置项

用于 startUpdate / wgtUpdate / smartUpdate。

基础内容

按钮与文案

显示与交互

颜色与主题

自定义 theme 对象示例：

theme: {
  headerGradient: ['#4F6DF5', '#7C3AED'],
  btnGradient: ['#4F6DF5', '#6366F1'],
  progressColor: '#06B6D4',
  maskColor: 'rgba(15, 23, 42, 0.55)'
}

内置主题 theme

Android 整包专用

wgt 专用

回调

失败重试

三、Android 应用市场 marketKey 一览

也可使用 LyUpdater.ANDROID_MARKETS 查看完整映射。

manifest 权限建议

在业务项目 manifest.json → App 模块配置 → Android 权限中确保包含：

• 访问网络
• 读写存储（视 targetSdk 与下载方式）
• 安装未知应用（Android 8+ 装 APK）

iOS 整包更新仅需跳转 App Store，无额外安装权限。

完整业务示例

import LyUpdater from '@/uni_modules/ly028-updater/js_sdk/index.js'

export async function checkAppUpdate() {
  const res = await uni.request({
    url: 'https://api.example.com/app/version',
    method: 'GET'
  })
  const data = res.data

  await LyUpdater.smartUpdate({
    appVersion: data.appVersion,
    wgtVersion: data.wgtVersion,
    appDownloadUrl: data.apkUrl,
    wgtDownloadUrl: data.wgtUrl,
    title: '发现新版本 v' + data.appVersion,
    content: data.changelog,
    versionCode: data.verCode,
    force: data.forceUpdate === true,
    theme: 'aurora',
    onSuccess: (r) => console.log('升级成功', r),
    onError: (e) => console.error(e)
  })
}

常见问题

Q：调用了 startUpdate 但没有弹窗？
A：检查是否在当前页面的 template 中写了 <ly-updater />。仅写在 App.vue 里无效。并确认已 LyUpdater.init()。

Q：运行提示基座不包含插件？
A：制作并运行 自定义调试基座，不要只用标准基座。

Q：iOS 整包 downloadUrl 填什么？
A：填 App Store 链接，例如 https://apps.apple.com/cn/app/id1234567890。详见上文 iOS 整包更新（App Store 地址）。

Q：iOS 能否应用内装 ipa？
A：不能。需在 downloadUrl 填写 App Store 地址，用户点击后跳转商店更新。

Q：能否只跳转市场不下载？
A：可以，直接调用 startMarket，不调用 startUpdate。

Q：版本比较用 UTS 还是 JS？
A：本插件版本比较在 js_sdk/version.js，请从 js_sdk/index.js 导入 compareVersion。

本地试用

插件市场用户请按上文 「方式一：插件市场试用」 操作。
插件作者本地改代码请打开仓库 example/ 目录，详见 docs/测试与发布.md。

更新日志

见 changelog.md