XuqmGroup-Web/docs-site/docs/rn/update.md

React Native 版本更新接入指南

包名：@xuqm/rn-update · 功能：App 版本检查、RN Bundle 热更新、打开商店

---

1. 安装

yarn add @xuqm/rn-update

rn-update 会自动依赖 @xuqm/rn-common 和 @xuqm/rn-sdk。

---

2. App 版本检查

import { UpdateSDK } from '@xuqm/rn-update'

const appUpdate = await UpdateSDK.checkAppUpdate()
if (appUpdate.needsUpdate) {
  console.log('新版本:', appUpdate.versionName)
  console.log('更新日志:', appUpdate.changeLog)
  console.log('下载地址:', appUpdate.downloadUrl)

  if (appUpdate.forceUpdate) {
    // 强制更新
    showForceUpdateModal(appUpdate)
  } else {
    // 可选更新
    showOptionalUpdateModal(appUpdate)
  }
}

App 版本号自动从原生模块读取，无需手动传入。开发/模拟器环境可调用 _devSetAppVersion 覆盖：

// 仅限开发环境使用
UpdateSDK._devSetAppVersion(100, '1.0.0')

---

3. 打开商店

await UpdateSDK.openStore(appUpdate.appStoreUrl, appUpdate.marketUrl)

• iOS：打开 appStoreUrl
• Android：打开 marketUrl

---

4. RN Bundle 热更新

4.1 注册插件

在插件 Bundle 的入口文件顶部注册插件元数据：

// plugin/index.ts
import { UpdateSDK } from '@xuqm/rn-update'
import meta from './plugin.json'

UpdateSDK.registerPlugin(meta)

plugin.json 示例：

{
  "moduleId": "home",
  "version": "1.2.3"
}

4.2 检查热更新

const rnUpdate = await UpdateSDK.checkRnUpdate('home')
if (rnUpdate.needsUpdate) {
  console.log('最新版本:', rnUpdate.latestVersion)
  console.log('下载地址:', rnUpdate.downloadUrl)
  console.log('更新说明:', rnUpdate.note)
  console.log('最低依赖版本:', rnUpdate.minCommonVersion)
}

4.3 下载并缓存 Bundle

// 下载 Bundle 源码
const source = await UpdateSDK.downloadRnBundle(rnUpdate.downloadUrl)

// 缓存到本地
await UpdateSDK.cacheRnBundle('home', rnUpdate.latestVersion, rnUpdate.md5, source)

// 读取已缓存的 Bundle
const cached = await UpdateSDK.getCachedRnBundle('home')
if (cached) {
  console.log('缓存版本:', cached.version)
  console.log('缓存时间:', cached.downloadedAt)
}

4.4 获取已注册插件版本

const version = UpdateSDK.getRegisteredPluginVersion('home')
console.log('当前运行版本:', version)

---

5. 强制更新处理

当 appUpdate.forceUpdate 为 true 时，建议业务层：

1. 弹出不可关闭的 Modal
2. 只允许用户点击「立即更新」
3. 调用 UpdateSDK.openStore() 跳转商店

function showForceUpdateModal(update: AppUpdateInfo) {
  // 使用 RN Modal 组件，设置不可取消
  Alert.alert(
    '发现重要更新',
    `当前版本已不可用，请升级至 ${update.versionName}`,
    [
      {
        text: '立即更新',
        onPress: () => UpdateSDK.openStore(update.appStoreUrl, update.marketUrl),
      },
    ],
    { cancelable: false }
  )
}

---

6. 多模块统一登录

Update 模块与 IM、Push 模块共享同一套登录态：

await XuqmSDK.initialize({ appKey: 'your_app_key' })
await XuqmSDK.login({ userId: 'user_001', userSig: 'your_user_sig_jwt' })
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作

---

7. 一键打包上传

SDK 提供 xuqm_release.mjs 脚本，可一键完成 RN Bundle 构建并上传至 XuqmGroup 版本管理服务：

node scripts/xuqm_release.mjs --platform android --env production

脚本执行流程：

1. 执行 react-native bundle 构建 JS Bundle
2. 自动提取模块 ID、版本号、更新日志
3. 上传 Bundle 到 XuqmGroup 后台
4. 返回发布结果

常用参数：

参数	说明
--platform	平台：android / ios
--env	环境：production / staging
--moduleId	模块 ID（如 home）
--forceUpdate	是否强制更新

在 package.json 中添加快捷命令：

{
  "scripts": {
    "xuqm:release": "node scripts/xuqm_release.mjs --platform android --env production"
  }
}