# React Native OTA 热更新指南

理解 React Native 热更新的原理、原生兼容边界、差分交付与灰度回滚，选择 Expo、CodePush 或 Pakta 接入路径。

## 什么是 React Native OTA update？ {#what-is-ota}

React Native OTA update（over-the-air update，空中更新或热更新）向已经安装的 App 分发 JavaScript 和随包资源，前提是安装包内的原生运行时能够执行这次更新。Pakta 使用 `rn-update` SDK 和 `pakta` CLI，为 Android、iOS 与 HarmonyOS 应用发布更新，也支持 Android 和 iOS 上的 Expo 原生构建。

例如，修改页面文案可以考虑热更新；新增原生相机模块则需要先发布新的原生安装包。OTA 交付不能替代原生版本发布或应用商店要求。

## 哪些改动可以热更新？ {#compatibility}

| 改动 | 交付方式 | 发布前检查 |
| --- | --- | --- |
| JavaScript 缺陷修复、页面文案 | 可以考虑 OTA | 只调用已安装 App 中存在的原生 API |
| 随包图片、样式 | 可以考虑 OTA | 资源完整，并在 Release 包中验证展示 |
| 原生依赖、权限、Config Plugin 配置 | 新原生包 | 重新构建、分发并登记基线 |
| React Native、Expo SDK、Hermes 升级 | 按新原生包安排发布 | 联合验证原生运行时和 bundle |
| 分发渠道身份 | 新 Pakta 原生包 | 渠道写入安装包，不能只改控制台 |

Expo 通过 [runtime versions](https://docs.expo.dev/eas-update/runtime-versions/) 描述原生层与更新层的兼容边界。Pakta 使用自己的原生包定向与兼容检查；Expo 的 `runtimeVersion` 不是 Pakta 的投放参数。

## Pakta 如何交付一次热更新？ {#delivery}

1. 在 App 中接入 `rn-update`，生成 Release 安装包。
2. 上传手机实际安装的那份原生包，登记更新基线。
3. 使用 CLI 把兼容的 JavaScript 和资源打成 `.ppk`。
4. 向指定应用、渠道和原生版本发布。
5. App 检查是否符合更新条件，下载后按配置的策略生效。
6. 观察下载、生效与健康事件，再扩大灰度范围。

存在有收益的补丁时，差分交付可以减少下载字节；全量包作为兜底。实际节省取决于基线和改动内容。详见[首次发布流程](/docs/publish)和[生产检查清单](/docs/bestpractice)。

## 应该选择哪一种 OTA 方案？ {#choose}

| 当前情况 | 评估方向 | 首先回答 |
| --- | --- | --- |
| 已有 EAS Update 工作流 | EAS Update 的运行时与渠道模型 | 是否真的需要更换 OTA 客户端？ |
| 正在使用 Microsoft CodePush | 独立 CodePush 或替代 SDK | 是否必须保留现有客户端协议？ |
| React Native 或 Expo 原生应用评估 Pakta | `rn-update` 与 Pakta 发布管理 | 能否发布新原生包并验证兼容性？ |
| HarmonyOS React Native 应用 | Pakta 的 HarmonyOS 接入 | 原生工具链与签名真机包能否跑通？ |

接入前先阅读 [Expo Updates 对比](/docs/expo-updates-vs-pakta)或 [CodePush 迁移指南](/docs/codepush-alternative)。比较实际运行时支持、恢复机制和运维责任，再用自己的 App 验证。

## 如何验证热更新真正生效？ {#verify}

使用真正的 Release 安装包，断开 Metro。改一处可见文案，向内部渠道发布，检查更新并按所选策略生效。确认预期的更新 hash 和版本，再验证离线启动与故障恢复。开发模式下重新加载成功不等于 OTA 已经跑通。

生产发布从小比例[灰度](/docs/channels)开始，关注[版本健康度](/docs/analytics)，保留兼容的稳定包。取消投放只能阻止继续分发，不能卸载设备上已经生效的更新。

## OTA 能替代应用商店发版吗？ {#native-release}

OTA 可以给已接入的原生 App 交付兼容的 JavaScript 与资源变化，但不能补入缺失的原生代码、给旧安装包装上 OTA SDK，或将其切换到新的原生运行时。分发前检查[商店发布清单](/docs/bestpractice#store-review)。

开始实践：先读[快速开始](/docs/introduction)，再选择 [Expo 配置](/docs/expo)或[原生接入](/docs/getting-started)。