Pakta
文档

让 App 检查更新

添加根组件，显示更新状态，设置何时下载和生效。

更新于 2026-09-14

本页内容

接入根组件

完成原生接入后，用 Provider 包裹根组件。替换为对应平台的 appKey：

Root.tsx
import { Pakta, UpdateProvider } from 'rn-update';
import App from './App';

const client = new Pakta({
  appKey: 'YOUR_PLATFORM_APP_KEY',
  updateStrategy: 'silentAndLater',
});

export default function Root() {
  return (
    <UpdateProvider client={client}>
      <App />
    </UpdateProvider>
  );
}

普通 RN 工程把注册入口指向这个 Root，保留你已有的应用名称：

index.js
import { AppRegistry } from 'react-native';
import { name as appName } from './app.json';
import Root from './Root';

AppRegistry.registerComponent(appName, () => Root);

Expo Router 工程在 app/_layout.tsx 中让 Provider 包裹现有的 Stack 或 Slot。同一进程只挂载一个 Provider，客户端在组件外创建，避免重渲染时重复初始化。

多平台 appKey

只有同时发布多个平台时才需要按平台选择。CLI 的 selectApp 会在 update.json 写入对应平台的 appId 和 appKey；先分别选好应用，再用下列代码替换单平台的 appKey：

按平台读取配置
import { Platform } from 'react-native';
import updateConfig from './update.json';

const platform = Platform.OS;
const configs = updateConfig as Record<string, { appKey: string }>;
const appKey = configs[platform]?.appKey;
if (!appKey) throw new Error(`Missing Pakta appKey for ${platform}`);

导入 JSON 后，其中数据会进入 App bundle。文件中只保存应用标识，不放 PAKTA_API_TOKEN。

显示版本

把下面组件放进 Provider 内部的页面。currentHash 为空表示运行内置 bundle。

UpdateStatus.tsx
import { Button, Text, View } from 'react-native';
import { useUpdate } from 'rn-update';

export function UpdateStatus() {
  const { packageVersion, currentHash, lastError, checkUpdate } = useUpdate();
  return (
    <View>
      <Text>Pakta demo A</Text>
      <Text>Native: {packageVersion}</Text>
      <Text>Update: {currentHash || 'embedded'}</Text>
      <Button title="Check update" onPress={() => { void checkUpdate(); }} />
      {lastError ? <Text>{lastError.message}</Text> : null}
    </View>
  );
}

选择生效时机

配置用户体验适合什么场景
silentAndLater静默下载，后续启动生效本教程与不中断操作的更新
silentAndNow下载完成立即重载可以接受立即中断的场景
alertUpdateAndIgnoreError提示用户更新，忽略检查错误SDK 默认策略
alwaysAlert更新和错误都提示内部诊断

checkStrategy 默认 both（启动和回到前台）；也可选 onAppStart、onAppResume。设为 null 关闭 JS 自动检查，原生冷启动检查仍可能下载更新；它不等于关闭全部更新能力。

手动更新

自定义更新按钮时设置 checkStrategy: null，在 Provider 内取得以下方法：

tsx
const { client } = useUpdate();

async function onUpdate() {
  if (!client) return;
  const info = await client.checkUpdate();
  if (!info?.update) return;
  const hash = await client.downloadUpdate(info);
  if (hash) await client.switchVersion(hash);
}

按钮执行期间禁用重复点击，并展示捕获的错误。useUpdateProgress() 返回下载进度，progress 存在时范围为 0–100。

健康确认与恢复

Provider 默认等待 1000 ms 后自动确认健康。关键初始化较晚时，把下面选项加入现有客户端，而不是新建第二个实例：

延迟健康确认
autoMarkSuccessDelayMs: 5000,
healthCheck: () => myCriticalModulesReady(),

myCriticalModulesReady 是你自己的就绪判断。返回 false 或抛错会跳过本次确认。需要完全接管时设置 autoMarkSuccess: false，在关键页面就绪后调用 useUpdate().markSuccess()。

未确认健康的更新启动失败时，原生保护可在后续启动回退；已经确认健康后的任意业务错误不保证触发回退。原生救援仍依赖网络、有效配置和可用修复投放。

扩展

  • 检查、下载与重载拦截：查 ClientOptions。

  • 测试二维码：useUpdate().parseTestQrCode(code)；生产可设 testChannel: false。测试通道。

  • 错误与更新版本信息关联：错误诊断。

测试通道

测试二维码用于指定测试更新，与原生包的固定分发渠道不是同一概念。首次接入不依赖扫码，按默认渠道发布即可。只有需要测试码入口时才在业务 UI 中接入解析，并控制哪些构建允许使用。

下一步

保留手机上这份 Release 包，进入发布第一条更新，把 Pakta demo A 改为 Pakta demo B。

完整按钮、错误处理和进度示例。