162 行
3.9 KiB
Markdown
162 行
3.9 KiB
Markdown
# React Native 版本更新接入指南
|
||
|
||
**包名**：`@xuqm/rn-update` · **功能**：App 版本检查、RN Bundle 热更新、打开商店
|
||
|
||
---
|
||
|
||
## 1. 安装
|
||
|
||
```bash
|
||
yarn add @xuqm/rn-update
|
||
```
|
||
|
||
`rn-update` 会自动依赖 `@xuqm/rn-common` 和 `@xuqm/rn-sdk`。
|
||
|
||
---
|
||
|
||
## 2. App 版本检查
|
||
|
||
```ts
|
||
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` 覆盖：
|
||
|
||
```ts
|
||
// 仅限开发环境使用
|
||
UpdateSDK._devSetAppVersion(100, '1.0.0')
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 打开商店
|
||
|
||
```ts
|
||
await UpdateSDK.openStore(appUpdate.appStoreUrl, appUpdate.marketUrl)
|
||
```
|
||
|
||
- iOS：打开 `appStoreUrl`
|
||
- Android：打开 `marketUrl`
|
||
|
||
---
|
||
|
||
## 4. RN 插件更新
|
||
|
||
插件更新以服务端返回的 release-set 为最小事务单位。一个 release-set 只包含目标
|
||
app/buz 及其 Common 依赖；SDK 会统一完成签名、宿主身份、整包版本、原生基线、
|
||
SHA-256 和最终依赖闭包校验。宿主不能分别下载后自行拼接版本。
|
||
|
||
进入 buz 前自动检查并安装：
|
||
|
||
```ts
|
||
await UpdateSDK.checkAndInstall('home', {
|
||
onProgress(moduleId, progress) {
|
||
console.log(moduleId, progress.percent)
|
||
},
|
||
})
|
||
```
|
||
|
||
需要由宿主展示确认弹窗时，检查与安装分开调用：
|
||
|
||
```ts
|
||
const plan = await UpdateSDK.check('home')
|
||
if (plan && (await showPluginUpdateDialog(plan))) {
|
||
await UpdateSDK.install(plan)
|
||
}
|
||
```
|
||
|
||
`check` 只检查，不下载、不修改本地状态。安装阶段会再次验证签名和检查时
|
||
记录的本地基线；计划已过期时必须重新检查。插件版本、路径和事务状态由原生层统一
|
||
管理，宿主不得另建一套缓存版本表。
|
||
|
||
---
|
||
|
||
## 5. 强制更新处理
|
||
|
||
当 `appUpdate.forceUpdate` 为 `true` 时，建议业务层：
|
||
|
||
1. 弹出不可关闭的 Modal
|
||
2. 只允许用户点击「立即更新」
|
||
3. 调用 `UpdateSDK.openStore()` 跳转商店
|
||
|
||
```ts
|
||
function showForceUpdateModal(update: AppUpdateInfo) {
|
||
// 使用 RN Modal 组件，设置不可取消
|
||
Alert.alert(
|
||
'发现重要更新',
|
||
`当前版本已不可用，请升级至 ${update.versionName}`,
|
||
[
|
||
{
|
||
text: '立即更新',
|
||
onPress: () => UpdateSDK.openStore(update.appStoreUrl, update.marketUrl),
|
||
},
|
||
],
|
||
{ cancelable: false }
|
||
)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 多模块统一登录
|
||
|
||
Update 模块与 IM、Push 模块共享同一套登录态：
|
||
|
||
```ts
|
||
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 版本管理服务：
|
||
|
||
```bash
|
||
XUQM_API_TOKEN=*** node scripts/xuqm_release.mjs --platform android --publish
|
||
```
|
||
|
||
脚本执行流程：
|
||
1. 按模块构建 JS/Hermes Bundle 和 Source Map
|
||
2. 生成根目录唯一的 `rn-manifest.json`
|
||
3. 生成 `<moduleId>.<platform>.xuqm.zip`
|
||
4. 上传归档并由服务端校验、签名
|
||
5. 按用户选择发布，返回不可变发布记录
|
||
|
||
常用参数：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--platform` | 平台：`android` / `ios` |
|
||
| `--module` | 可重复传入，只构建或发布指定模块 |
|
||
| `--note` | 本次发布说明 |
|
||
| `--publish` | 上传后立即发布 |
|
||
| `--bugcollect` | `platform` 上传 Source Map；`disabled` 仅保留本地产物 |
|
||
|
||
在 `package.json` 中添加快捷命令：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"xuqm:release": "node scripts/xuqm_release.mjs --platform android --publish"
|
||
}
|
||
}
|
||
```
|
