RN0.72.5版本迁移升级实战避坑全记录

原创

已于 2026-05-14 11:15:50 修改 · 263 阅读

文章标签：

#react native #react.js #javascript

于 2026-05-14 11:13:06 首次发布

一、背景

1.1 升级动机

React Native 0.70.0 发布于 2022 年 9 月，已进入维护末期。0.72.5 作为 0.72 系列的稳定版本，带来：

Hermes 引擎 成为默认 JS 引擎，启动速度与内存占用显著优化
新架构（Fabric / TurboModules） 基础能力完善，为后续迁移铺垫
Gradle 7.x + AGP 7.x 原生支持，移除旧版构建兼容代码
关键 Bug 修复 与社区生态适配

1.2 升级原则

原则	说明
最小化变更	仅升级 RN 核心及其紧耦合依赖，不动业务代码
保持构建工具版本	Gradle 7.5.1 / AGP 7.4.2 / Kotlin 1.8.20 不变
前后兼容	Android 原生侧 API 平滑过渡，JS 侧业务逻辑不改动
稳定优先	优先确保编译通过 + 运行时无闪退，再考虑性能优化

二、版本变更一览

2.1 直接变更

组件	升级前	升级后	变更原因
react-native	0.70.0	0.72.5	主版本升级
react	18.1.0	18.2.0	RN 0.72.5 最低要求 React 18.2
compileSdk	31	33	RN 0.72 要求
targetSdk	31	33	跟随 compileSdk
buildTools	31.0.0	33.0.0	跟随 compileSdk
async-storage	1.16.3	1.21.0	修复 RN 0.72 peer dependency 不兼容

2.2 保持不变

组件	版本	原因
Gradle	7.5.1	AGP 7.4.2 支持，无需升级
AGP	7.4.2	RN 0.72 要求 ≥ 7.3.1，当前已满足
Kotlin	1.8.20	稳定版本，无兼容性问题
Java	11	项目标准，保持不变
minSdk	23	不变

2.3 关键架构变化

RN 0.70.0                          RN 0.72.5
─────────────────────────          ─────────────────────────
JS 引擎：JSC (JavaScriptCore)      JS 引擎：Hermes（默认）
Android 产物：react-native AAR     Android 产物：react-android + hermes-android
Autolink：native_modules.gradle    Autolink：com.facebook.react 插件 + native_modules.gradle
Maven 来源：node_modules 本地       Maven 来源：Maven Central 远程
MainReactPackage：存在             MainReactPackage：保留（AAR 中仍存在）

三、详细修改清单

3.1 构建配置（5 个文件）

`package.json`

{
  "dependencies": {
-   "react": "18.1.0",
+   "react": "18.2.0",
-   "react-native": "0.70.0",
+   "react-native": "0.72.5",
-   "@react-native-async-storage/async-storage": "1.16.3",
+   "@react-native-async-storage/async-storage": "1.21.0"
  },
  "overrides": {
-   "react-native": "0.70.0"
+   "react-native": "0.72.5"
  }
}

执行 yarn install 安装依赖。

`gradle/libs.versions.toml`

[versions]
- compileSdk = "31"
+ compileSdk = "33"
- ta

最低0.47元/天解锁文章

RN0.72.5版本迁移升级实战避坑全记录

目录

一、背景

1.1 升级动机

1.2 升级原则

二、版本变更一览

2.1 直接变更

2.2 保持不变

2.3 关键架构变化

三、详细修改清单

3.1 构建配置（5 个文件）

package.json

gradle/libs.versions.toml

`package.json`

`gradle/libs.versions.toml`