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 插件更新

插件更新以服务端返回的 release-set 为最小事务单位。一个 release-set 只包含目标 app/buz 及其 Common 依赖；SDK 会统一完成签名、宿主身份、整包版本、原生基线、 SHA-256 和最终依赖闭包校验。宿主不能分别下载后自行拼接版本。

进入 buz 前自动检查并安装：

await UpdateSDK.checkAndInstallPlugin('home', {
  onProgress(moduleId, progress) {
    console.log(moduleId, progress.percent)
  },
})

需要由宿主展示确认弹窗时，检查与安装分开调用：

const plan = await UpdateSDK.checkPluginRelease('home')
if (plan && (await showPluginUpdateDialog(plan))) {
  await UpdateSDK.installPluginRelease(plan)
}

checkPluginRelease 只检查，不下载、不修改本地状态。安装阶段会再次验证签名和检查时记录的本地基线；计划已过期时必须重新检查。插件版本、路径和事务状态由原生层统一管理，宿主不得另建一套缓存版本表。

5. 强制更新处理

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

弹出不可关闭的 Modal
只允许用户点击「立即更新」
调用 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 版本管理服务：

XUQM_API_TOKEN=*** node scripts/xuqm_release.mjs --platform android --publish

脚本执行流程：

按模块构建 JS/Hermes Bundle 和 Source Map
生成根目录唯一的 rn-manifest.json
生成 <moduleId>.<platform>.xuqm.zip
上传归档并由服务端校验、签名
按用户选择发布，返回不可变发布记录

常用参数：

参数	说明
`--platform`	平台：`android` / `ios`
`--module`	可重复传入，只构建或发布指定模块
`--note`	本次发布说明
`--publish`	上传后立即发布
`--bugcollect`	`platform` 上传 Source Map；`disabled` 仅保留本地产物

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

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

4.0 KiB 原始文件 Blame 文件历史 Unescape Escape