55551114创建于 8 天前历史提交

RN框架版本升级指导

本文档针对两种升级场景提供指导：

小版本升级：在同一 RNOH 大版本分支内升级补丁版本（例如 0.72.50 → 0.72.133、0.82.3 → 0.82.18、0.84.0 → 0.84.1），通常只需更新依赖版本号。
大版本升级：跨社区 RN 大版本升级，当前文档覆盖以下路径：

小版本升级

注意：如果您之前使用的是本地依赖，请先参考如何从本地依赖切换至远程依赖进行切换。

依据版本说明中的版本号，升级所有oh-package.json5的dependencies字段中@rnoh/react-native-openharmony的版本；
点击File->Sync and Refresh Project安装新版依赖;
升级RN工程根目录的package.json中的@react-native-oh/react-native-harmony及@react-native-oh/react-native-harmony-cli依赖版本号;
在RN工程根目录重新执行npm i;

如何从本地依赖切换至远程依赖

在原生工程中

删除 entry/oh-package.json5 的 dependencies 字段，例：

{
...
  "dependencies": {
- "@rnoh/react-native-openharmony": "./libs/react_native_openharmony-X.X.X.X.har"
  },
...
}

ohpm i @rnoh/react-native-openharmony@x.x.x

在RN工程中

删掉RN工程根目录的 package.json的dependencies 字段，例：

...
  "dependencies": {
- "react-native-harmony": "file:../react-native-harmony/rnoh-react-native-harmony-x.x.x.tgz",
  },
...

在 AwesomeProject 目录下运行安装依赖包命令：

npm i @react-native-oh/react-native-harmony@x.x.x

或

yarn add @react-native-oh/react-native-harmony@x.x.x

修改 metro.config.js 文件，例：

...
-  const {createHarmonyMetroConfig} = require('react-native-harmony/metro.config');
+  const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
...
  module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({
-    reactNativeHarmonyPackageName: 'react-native-harmony',
+    reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
  }), config);

注意：如果引入的包依赖其他的包，请参考如何在三方库或自定义module中引入rnoh的依赖

如何使用本地包安装鸿蒙化依赖

在原生工程中

将依赖包置于一个自定义的路径下，例：NativeProject/libs/react_native_openharmony-X.X.X.X.har。
修改 entry/oh-package.json5 的 dependencies 字段，例：

{
...
  "dependencies": {
+ "@rnoh/react-native-openharmony": "./libs/react_native_openharmony-X.X.X.X.har"
  },
...
}

在RN工程中

修改RN工程根目录的 package.json的dependencies 字段，例：

...
  "dependencies": {
+ "react-native-harmony": "file:../react-native-harmony/rnoh-react-native-harmony-x.x.x.tgz",
  },
...

确保您的 rnoh-react-native-harmony-x.x.x.tgz 文件所在的上级目录中存在名为 react-native-harmony-cli 的文件夹，并在该文件夹内放置对应版本的 rnoh-react-native-harmony-cli-x.x.x.tgz 文件。
修改 metro.config.js 文件，例：

...
-  const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
+  const {createHarmonyMetroConfig} = require('react-native-harmony/metro.config');
...
  module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({
-    reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
+    reactNativeHarmonyPackageName: 'react-native-harmony',
  }), config);

注意：如果引入的包依赖其他的包，请参考如何在三方库或自定义module中引入rnoh的依赖。

大版本升级

本部分提供不同大版本升级场景的指导：

从 0.72.x 升级到 0.77.x
从 0.77.x 升级到 0.82.x
从 0.82.x 升级到 0.84.x

从 0.72.x 升级到 0.77.x

这一部分介绍如何将鸿蒙化RN工程从 0.72.x 升级到 0.77.x

升级RN项目依赖版本

以下为已知必须升级的依赖

{
    ...
    "dependencies": {
        "react": "18.3.1",
        "react-native": "0.77.1"
    },
    "devDependencies": {
        "@react-native-community/cli": "15.0.1",
        "@react-native/babel-preset": "0.77.1",
    },
}

上述所有依赖如果当前72项目中没有需要补充，版本都请和列出的保持一致
metro-react-native-babel-preset 因上游重构不再需要，可以删除
此外上游社区还升级了一些开发依赖，可以自行选择是否跟随社区升级

{
    ...
    "devDependencies": {
        "@babel/core": "^7.25.2",
        "@babel/preset-env": "^7.25.3",
        "@babel/runtime": "^7.25.0",
        "@react-native-community/cli-platform-android": "15.0.1",
        "@react-native-community/cli-platform-ios": "15.0.1",
        "@react-native/eslint-config": "0.77.1",
        "@react-native/metro-config": "0.77.1",
        "@react-native/typescript-config": "0.77.1",
        "@types/jest": "^29.5.13",
        "@types/react": "^18.2.6",
        "@types/react-test-renderer": "^18.0.0",
        "eslint": "^8.19.0",
        "jest": "^29.6.3",
        "prettier": "3.0.0",
        "react-test-renderer": "18.3.1",
        "typescript": "5.0.4"
    }

}

提示：在VSCode中可以复制所有的 devDependencies 到待升级项目的 devDependencies 中，重复的key会被划线，删掉老的即完成依赖补充和升级

升级/添加RNOH前端依赖后，运行npm i安装依赖。若遇依赖冲突错误，可根据错误信息调整package.json中依赖库的版本来解决
- 升级 dependencies: "react-native-harmony" 或 "@xxx/react-native-harmony"
  
  注意：保持原来的包名。如果原来 react-native-harmony 前面没有@组织前缀那么升级时也不要添加，如果原来有就保持之前的 "@xxx/react-native-harmony"
- 添加 devDependencies: "@react-native-oh/react-native-harmony-cli"
- 具体版本号请参考 RNOH版本规划
修改两处配置，其中第二处可选。注意只修改配置中下面列出的字段
1. babel.config.js
  - 如果文件存在，修改module.exports中的presets字段，将 'module:metro-react-native-babel-preset' 替换为 'module:@react-native/babel-preset'
  - 如果文件不存在创建该文件，内容按照下方示例填写
```
module.exports = {
  presets: ['module:@react-native/babel-preset'],
};
```
2. （可选）tsconfig.json
  - 需要在 package.json 中添加 devDependencies "@react-native/typescript-config": "0.77.1"
  - 修改tsconfig.json，中的 extend 字段，改为
```
{
    "extends": "@react-native/typescript-config/tsconfig.json"
}
```
打包前端bundle时，如遇到依赖冲突错误，可修改package.json、metro.config.js、babel.config.js等配置文件，根据错误提示进行调整即可
修改鸿蒙工程中所有oh-package.json5中配置的@rnoh/react-native-openharmony依赖版本，具体版本号请参考 RNOH版本规划
在鸿蒙工程目录下运行 ohpm i 或在DevEco Studio中点击 File->Sync and Refresh Project 安装依赖
打应用hap包，安装进行测试

参考资料：

从 0.77.x 升级到 0.82.x

本节描述如何将RN工程从 0.77.x 版本升级到 0.82.x 版本

升级RN项目依赖版本

以下为已知必须升级的依赖

{
    ...
    "dependencies": {
        "react": "19.1.1",
        "react-native": "0.82.1"
    },
    "devDependencies": {
        "@react-native-community/cli": "20.0.0",
        "@react-native/babel-preset": "0.82.1",
    },
}

上述所有依赖如果当前77项目中没有需要补充，版本都请和列出的保持一致
此外上游社区还升级了一些开发依赖，可以自行选择是否跟随社区升级

{
    ...
    "devDependencies": {
        "@babel/core": "^7.25.2",
        "@babel/preset-env": "^7.25.3",
        "@babel/runtime": "^7.25.0",
        "@react-native-community/cli-platform-android": "20.0.0",
        "@react-native-community/cli-platform-ios": "20.0.0",
        "@react-native/eslint-config": "0.82.1",
        "@react-native/metro-config": "0.82.1",
        "@react-native/typescript-config": "0.82.1",
        "@types/jest": "^29.5.13",
        "@types/react": "^19.1.0",
        "@types/react-test-renderer": "^19.1.0",
        "eslint": "^8.19.0",
        "jest": "^29.7.0",
        "prettier": "3.3.0",
        "react-test-renderer": "18.3.1",
        "typescript": "^5.5.4"
    }

}

提示：在VSCode中可以复制所有的 devDependencies 到待升级项目的 devDependencies 中，重复的key会被划线，删掉老的即完成依赖补充和升级

升级/添加RNOH前端依赖后，运行npm i安装依赖。若遇依赖冲突错误，可根据错误信息调整package.json中依赖库的版本来解决
- 升级 dependencies: "react-native-harmony" 或 "@xxx/react-native-harmony"
  
  注意：保持原来的包名。如果原来 react-native-harmony 前面没有@组织前缀那么升级时也不要添加，如果原来有就保持之前的 "@xxx/react-native-harmony"
- 确保 devDependencies 中已包含: "@react-native-oh/react-native-harmony-cli"
检查并更新配置文件
1. babel.config.js
  - 确认module.exports中的presets字段使用 'module:@react-native/babel-preset'
```
module.exports = {
  presets: ['module:@react-native/babel-preset'],
};
```
打包前端bundle时，如遇到依赖冲突错误，可修改package.json、metro.config.js、babel.config.js等配置文件，根据错误提示进行调整即可

升级过程中，上游React Native社区引入了一些不兼容变更，需要开发者自行适配。常见的不兼容变更包括但不限于：

Refs废弃：字符串形式的 refs 已被废弃，React 19 中将正式移除对它的支持。(https://github.com/facebook/react-native/commit/223e98cc4b656b94b48c88940114bfdc025f8ddf)
NewAppScreen组件被移除：对NewAppScreen 进行重新设计，并迁移至 react-native/new-app-screen 中。(https://github.com/facebook/react-native/commit/3cf01020071c76f40499878674cc7aaf5dbe168a)
infolog的变更：从 react-native 包中移除了 infoLog。（https://github.com/facebook/react-native/commit/8a0cfec81584e966c9e6ea0f5e438022e0129bcd）
ReactNativeFeatureFlags变更：将 ReactNativeFeatureFlags 移至 src/private 。（https://github.com/facebook/react-native/commit/fb4587780e8d6111139d73598a9a26ff392dee28）

请查阅上游社区的详细变更说明，具体的不兼容变更详情，请参考下方参考资料中的上游社区不兼容变更文档

参考资料：

从 0.82.x 升级到 0.84.x

本节描述如何将RN工程从 0.82.x 版本升级到 0.84.x 版本

升级RN项目依赖版本

以下为已知必须升级的依赖

{
    ...
    "dependencies": {
        "react": "19.2.3",
        "react-native": "0.84.1"
    },
    "devDependencies": {
        "@react-native-community/cli": "20.1.0",
        "@react-native/babel-preset": "0.84.1",
    },
}

上述所有依赖如果当前82项目中没有需要补充，版本都请和列出的保持一致
此外上游社区还升级了一些开发依赖，可以自行选择是否跟随社区升级

{
    ...
    "devDependencies": {
        "@babel/core": "^7.25.2",
        "@babel/preset-env": "^7.25.3",
        "@babel/runtime": "^7.25.0",
        "@react-native-community/cli": "20.1.0",
        "@react-native-community/cli-platform-android": "20.1.0",
        "@react-native-community/cli-platform-ios": "20.1.0",
        "@react-native/babel-preset": "0.84.1",
        "@react-native/eslint-config": "0.84.1",
        "@react-native/metro-config": "0.84.1",
        "@react-native/typescript-config": "0.84.1",
        "@types/jest": "^29.5.13",
        "@types/react": "^19.2.0",
        "@types/react-test-renderer": "^19.1.0",
        "eslint": "^8.19.0",
        "jest": "^29.6.3",
        "prettier": "2.8.8",
        "react-test-renderer": "19.2.3",
        "typescript": "^5.8.3"
    }
}

提示：在VSCode中可以复制所有的 devDependencies 到待升级项目的 devDependencies 中，重复的key会被划线，删掉老的即完成依赖补充和升级

升级/添加RNOH前端依赖后，运行npm i安装依赖。若遇依赖冲突错误，可根据错误信息调整package.json中依赖库的版本来解决
- 升级 dependencies: "react-native-harmony" 或 "@xxx/react-native-harmony"
  
  注意：保持原来的包名。如果原来 react-native-harmony 前面没有@组织前缀那么升级时也不要添加，如果原来有就保持之前的 "@xxx/react-native-harmony"
- 确保 devDependencies 中已包含: "@react-native-oh/react-native-harmony-cli"
打包前端bundle时，如遇到依赖冲突错误，可修改package.json、metro.config.js、babel.config.js等配置文件，根据错误提示进行调整即可

参考资料：