更新记录

1.0.0（2026-01-23） 下载此版本

1.支持注册账号单独使用 2.数据隔离不污染

平台兼容性

uni-app

其他

wrap-version-update-plugin

uni-app 版本更新插件（Vue3），支持热更新（wgt）和整包更新（apk/ipa）。

功能特性

• ✅ 自动检查版本更新
• ✅ 支持 wgt 热更新（无需重新安装）
• ✅ 支持整包更新（apk/ipa）
• ✅ 支持强制更新
• ✅ 支持自定义更新提示
• ✅ 提供组件和 SDK 两种使用方式
• ✅ 支持多环境配置（prod/dev/test）

安装

方式一：通过 uni_modules（推荐）

1. 将 wrap-version-update-plugin 文件夹复制到项目的 uni_modules 目录下
2. 在 pages.json 中配置 easycom（如果自动识别失败）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^wrap-version-update$": "@/uni_modules/wrap-version-update-plugin/components/wrap-version-update.vue"
    }
  }
}

3. 如果配置后仍无法识别，请使用方式二手动导入

方式二：手动导入（推荐，更稳定）

在需要使用的页面中手动导入组件：

<script setup>
import WrapVersionUpdate from '@/uni_modules/wrap-version-update-plugin/components/wrap-version-update.vue';
</script>

<template>
  <wrap-version-update
    :app-id="'your-app-id'"
    :api-base="'http://10.0.63.178:3000'"
  />
</template>

使用方法

方式一：组件方式（推荐）

重要：如果遇到组件无法解析的错误，请先手动导入组件！

在页面中使用组件：

<template>
  <view>
    <wrap-version-update
      :app-id="'your-app-id'"
      :platform="'android'"
      :env="'prod'"
      :api-base="'http://10.0.63.178:3000'"
      :auto="true"
      :show-confirm="true"
      @check="onCheck"
      @finish="onFinish"
      @error="onError"
      @download="onDownload"
      @install="onInstall"
    />
    <!-- 你的页面内容 -->
  </view>
</template>

<script setup>
// 手动导入组件（如果 easycom 自动识别失败）
import WrapVersionUpdate from '@/uni_modules/wrap-version-update-plugin/components/wrap-version-update.vue';

const onCheck = (res) => {
  console.log('检查更新结果:', res);
};

const onFinish = (res) => {
  console.log('无需更新:', res);
};

const onError = (err) => {
  console.error('更新错误:', err);
};

const onDownload = (info) => {
  console.log('开始下载:', info);
};

const onInstall = (info) => {
  console.log('安装完成:', info);
};
</script>

方式二：SDK 方式（手动控制）

如果需要在业务代码中手动控制更新流程：

import { checkUpdate } from '@/uni_modules/wrap-version-update-plugin/js_sdk/version-service.js';

// 检查更新
const checkVersion = async () => {
  try {
    const res = await checkUpdate({
      appId: 'your-app-id',
      platform: 'android', // 'android' | 'ios'
      env: 'prod', // 'prod' | 'dev' | 'test'
      uniqueId: '', // 可选：设备唯一标识
      apiBase: 'http://10.0.63.178:3000',
      currentBuild: 0 // 可选：当前构建号
    });

    if (res.needUpdate) {
      // 处理更新逻辑
      console.log('发现新版本:', res.version);
      console.log('更新说明:', res.desc);
      console.log('是否强制更新:', res.force);
      console.log('wgt 下载地址:', res.wgtUrl);
      console.log('apk 下载地址:', res.apkUrl);
    } else {
      console.log('已是最新版本');
    }
  } catch (error) {
    console.error('检查更新失败:', error);
  }
};

API 参数说明

组件 Props

组件 Events

SDK 方法

checkUpdate(options)

检查版本更新

参数：

{
  appId: String,        // 必填：应用 ID
  platform: String,    // 可选：'android' | 'ios'，默认 'android'
  env: String,         // 可选：'prod' | 'dev' | 'test'，默认 'prod'
  uniqueId: String,    // 可选：设备唯一标识
  apiBase: String,     // 必填：API 基础地址
  currentBuild: Number // 可选：当前构建号，默认 0
}

返回值：

{
  needUpdate: Boolean,  // 是否需要更新
  version: String,      // 版本号
  build: Number,        // 构建号
  desc: Array,          // 更新说明（数组）
  force: Boolean,       // 是否强制更新
  apkUrl: String,       // APK 下载地址
  wgtUrl: String,       // WGT 热更新地址
  size: String,         // 文件大小
  hash: String,         // 文件哈希值
  currentBuild: Number  // 当前构建号
}

API 接口规范

插件会向以下接口发送请求：

GET {apiBase}/api/version/latest

请求参数：

响应格式：

{
  "version": "1.0.1",
  "build": 2,
  "desc": ["修复了一些 bug", "优化了用户体验"],
  "force": false,
  "apkUrl": "https://example.com/app.apk",
  "wgtUrl": "https://example.com/app.wgt",
  "size": "10.5MB",
  "hash": "abc123..."
}

更新流程

1. 自动检查：组件挂载时（auto=true）自动检查更新
2. 手动检查：通过组件暴露的 runCheck 方法手动触发
3. 更新提示：如果 showConfirm=true，会显示更新确认弹窗
4. 下载安装：
   • 优先尝试 wgt 热更新（无需重新安装）
   • 如果 wgt 更新失败或不存在，则使用整包更新（apk/ipa）
5. 强制更新：如果 force=true，用户必须更新，否则退出应用

使用示例

示例 1：基础使用

<template>
  <wrap-version-update
    :app-id="'my-app'"
    :api-base="'http://10.0.63.178:3000'"
  />
</template>

示例 2：手动控制更新

<template>
  <view>
    <button @click="handleCheckUpdate">检查更新</button>
    <wrap-version-update
      ref="updateRef"
      :app-id="'my-app'"
      :api-base="'http://10.0.63.178:3000'"
      :auto="false"
      :show-confirm="false"
      @check="handleUpdateCheck"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue';

const updateRef = ref(null);

const handleCheckUpdate = () => {
  updateRef.value?.runCheck();
};

const handleUpdateCheck = (res) => {
  if (res.needUpdate) {
    uni.showModal({
      title: '发现新版本',
      content: res.desc.join('\n'),
      success: (modalRes) => {
        if (modalRes.confirm) {
          // 手动触发下载
          // 组件会自动处理下载和安装
        }
      }
    });
  }
};
</script>

示例 3：多环境配置

<template>
  <wrap-version-update
    :app-id="appId"
    :platform="platform"
    :env="env"
    :api-base="apiBase"
    :current-build="currentBuild"
  />
</template>

<script setup>
import { computed } from 'vue';

const appId = 'my-app';
const platform = uni.getSystemInfoSync().platform === 'android' ? 'android' : 'ios';
const env = process.env.NODE_ENV === 'production' ? 'prod' : 'dev';
const apiBase = env === 'prod' 
  ? 'http://10.0.63.178:3000' 
  : 'http://10.0.63.178:3000';
const currentBuild = plus.runtime.versionCode || 0;
</script>

注意事项

1. 5+ App 环境：wgt 热更新和整包安装需要 5+ App 环境（使用 HBuilderX 打包）
2. 权限配置：整包更新需要配置下载和安装权限
3. API 接口：确保后端 API 接口返回格式符合规范
4. 网络请求：确保应用有网络访问权限
5. 强制更新：强制更新时，用户取消会退出应用（Android 平台）

常见问题

Q: 为什么 wgt 更新不生效？

A: 确保：

• 使用 HBuilderX 打包的 5+ App
• wgt 包版本号大于当前版本
• wgt 包签名与当前应用一致

Q: 如何获取当前构建号？

A: 可以通过以下方式获取：

// 方式 1：使用 plus.runtime
const currentBuild = plus.runtime.versionCode || 0;

// 方式 2：从 manifest.json 读取
// 需要在打包时配置 versionCode

Q: 支持 H5 和小程序吗？

A: 目前主要支持 5+ App 环境。H5 和小程序平台需要根据实际情况调整实现。

更新日志

v0.1.0

• 初始版本
• 支持 wgt 热更新
• 支持整包更新
• 支持强制更新
• 提供组件和 SDK 两种使用方式

许可证

MIT