更新记录

0.0.1（2026-07-23）

平台兼容性

uni-app(4.0)

uni-app x(4.0)

unify-upgrade

uni-app App 版本检测与更新弹窗组件 | 支持 Vue2/Vue3、Android/iOS | APK 整包更新 · WGT 热更新 · iOS AppStore 跳转

💰 授权说明

• ✅ 购买后可用于 不限数量 的商业项目
• ❌ 禁止将本插件（含源码）在任何平台二次分发、转售、开源
• 📩 源码获取 / 商务合作请联系 QQ：XXXXXXXX

⚠️ 编译版为加密组件，功能与源码版完全一致，仅无法查看和修改内部实现。如需自定义 UI 样式或扩展逻辑，请购买源码版。

🖼️ 效果预览

🎬 演示 GIF 录制中，敬请期待！

当前版本功能完整可用，下方为 UI 设计稿预览：

Android WGT 热更新	Android APK 整包更新	iOS AppStore 跳转

📦 平台兼容性

✨ 功能特性

• 双模式更新：自动识别 .apk / .wgt 后缀，分别走整包安装或热更新流程
• 版本号智能对比：支持语义化版本（1.2.9）与纯数字版本（182 / "182"）混合对比，自动归一化
• 字段完全映射：请求参数、响应顶层字段、响应 data 字段均可通过 props 自定义映射，适配任意后端接口
• 强制/可选更新：支持服务端下发强制更新标识，强制模式下隐藏"暂不更新"按钮
• WGT 安全预校验：安装前解压读取 WGT 内 manifest.json 版本号，避免低版本包覆盖导致 -1205 错误
• Logo 有效性验证：异步 HEAD 请求探测 Logo URL 是否真实可达且为图片，无效时自动隐藏 Logo 区域
• TabBar 联动：弹窗弹出/关闭时自动控制原生 TabBar 显隐，避免层级遮挡
• 页面滚动锁定：弹窗期间禁用 WebView 弹性滚动，防止背景穿透
• DOM 挂载优化：组件自动移至 document.body，不受父级 overflow/transform 影响

🚀 快速使用

1. 导入插件

在 HBuilderX 中打开你的 uni-app 项目：

1. 点击菜单 工具 → 插件安装 → 选择从 DCloud 插件市场导入
2. 或在 插件市场页面 点击「导入 HBuilderX」按钮
3. 确认导入到项目的 uni_modules 目录下

2. 引入组件

在 App.vue 或首页中使用：

<template>
  <unify-upgrade ref="upgradeRef" check-api="https://api.example.com/app/check-update" />
</template>

<script>
export default {
  onLaunch() {
    // #ifdef APP-PLUS
    this.$refs.upgradeRef && this.$refs.upgradeRef.versionCheck();
    // #endif
  }
}
</script>

3. Props 配置

appLogo 注意事项

组件会在 mounted 时发起 HEAD 请求 验证 Logo URL：

• ✅ 状态码 2xx 且 Content-Type 以 image/ 开头 → 正常显示
• ❌ 请求失败 / 非图片类型 / 超时(5s) → 自动隐藏 Logo 区域，不影响弹窗正常使用
• ⚠️ 若你的 CDN 不支持 HEAD 请求或有跨域限制，请确保服务端正确配置 CORS，否则 Logo 将不会显示

checkApiResponseDataFields 默认值

{
  versionName: "versionName",                    // 远程版本名称（支持 "1.2.9" / 182 / "182"）
  versionCode: "versionCode",                    // 远程版本号（整数），versionName 缺失时回退对比
  forcedUpgrade: "forcedUpgrade",                // 是否强制更新（true/1=强制）
  iosVersionResourceLink: "iosVersionResourceLink",         // iOS 更新链接
  androidVersionResourceLink: "androidVersionResourceLink", // Android 更新链接
  releaseNotes: "releaseNotes"                   // 更新说明文本
}

4. 服务端响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "versionName": 183,
    "versionCode": 183,
    "forcedUpgrade": false,
    "androidVersionResourceLink": "https://cdn.example.com/app/release/app.wgt",
    "iosVersionResourceLink": "https://apps.apple.com/app/id123456789",
    "releaseNotes": "新增深色模式,修复消息推送延迟,优化启动速度"
  }
}

💡 versionName 支持返回整数 183、字符串 "183" 或语义化版本 "1.8.3"，组件内部会自动归一化为 1.8.3 进行逐段对比。

⚙️ 进阶说明

版本号对比规则

WGT 热更新注意事项

1. WGT 包的 manifest.json 中 versionName 必须高于 当前 App 版本，否则安装时会报 -1205 错误
2. 组件已在安装前增加预校验：解压 WGT 读取版本号并对比，版本不匹配时拦截安装并提示用户
3. 打包 WGT 时请确保勾选 "生成 wgt 包" 而非 "生成 apk/ipk 包"

❓ 常见问题

Q: 支持离线打包 / 云打包吗？

A: 均支持。编译版为加密组件，HBuilderX 云打包和离线打包均可正常集成，无额外配置。

Q: WGT 热更新提示 -1205 错误？

A: 表示 WGT 包内的版本号 ≤ 当前 App 版本号。请检查：

1. WGT 打包时 manifest.json 中的版本号是否正确递增
2. 服务端下发的 androidVersionResourceLink 指向的 WGT 文件是否为最新版本

Q: Logo 不显示怎么办？

A: 组件会自动验证 Logo URL 有效性。请检查：

1. URL 是否可直接在浏览器中打开且为图片
2. CDN 是否支持 HEAD 请求方法
3. 是否存在跨域限制（需配置 Access-Control-Allow-Origin）
4. 图片格式是否为 png/jpg/gif/webp/svg/bmp/ico

Q: 弹窗被页面元素遮挡 / 背景可以滚动？

A: 组件已内置 DOM 挂载至 body + 滚动锁定机制。如仍出现问题，请确认：

1. 使用的是最新版 HBuilderX（≥3.1.0）
2. 未在组件外层手动包裹 fixed/absolute 容器

Q: 如何从编译版升级到源码版？

A: 联系 QQ XXXXXXXX 补差价即可，提供完整源码及后续更新权限。

📋 更新日志

详见 changelog.md

📄 许可协议

购买即表示同意 DCloud 插件市场许可协议。未经授权不得二次分发、转售或开源本插件。