一、背景知识速览

1.1 什么是 RNOH？

React Native for OpenHarmony (RNOH) 是让 React Native 应用能直接运行在 HarmonyOS 设备上的核心库。它由华为与 Software Mansion 等合作伙伴共同开发，基于 React Native 新架构（Fabric）构建，确保性能与可靠性。

目前已有 YY、小红书（Little Red Book）、携程 等知名应用采用此方案，超过 2700万台 设备运行在 HarmonyOS NEXT 上。

1.2 鸿蒙化 RN 的技术特点

相较于 Android/iOS 平台将 RN 组件转化为原生 UI 控件，鸿蒙上的转化路径更短——直接将 JS/React 组件代码转化为 ArkUI 后台 C++ 信息，而非转化为 ArkUI 控件，从而提升渲染效率。

---

二、环境安装前置准备

2.1 软件版本要求（核心避坑点）

软件	推荐版本	说明
DevEco Studio	4.1.3.400+ / 3.1.0.501+	鸿蒙官方 IDE，需支持 ArkUI 3.0+ 桥接 API
Node.js	v16.18.0 LTS 或 v18.14.1	与 RN 0.72.x 兼容性最佳
JDK	JDK 11	DevEco Studio 3.0+ 强制要求
React Native	0.72.5 或 0.77.1	RNOH 当前官方支持的版本
HarmonyOS SDK	API 20+（对应 NEXT Developer Preview1）

⚠️ 关键提醒：RNOH 目前支持 RN 0.72.5 和 0.77.1 两个版本。0.72.5 版本的框架和三方库生态更为成熟，推荐生产项目优先考虑。

2.2 鸿蒙开发环境安装

Step 1：注册开发者账号并申请权限

目前最新版 OpenHarmony SDK 及 RNOH 相关 npm 包尚未完全对外开放，个人开发者需先申请白名单成为合作伙伴。

• 登录 HarmonyOS 应用开发门户 注册账号

• 进入 DevEco Studio 套件货架中心申请白名单

Step 2：下载并安装 DevEco Studio

白名单通过后，下载对应版本的 DevEco Studio 安装包并完成安装。启动后根据引导配置 SDK 使用路径。

Step 3：配置 hdc 环境变量

hdc 是 OpenHarmony 调试命令行工具，位于 SDK 的 toolchains 目录下：

text

# Windows 环境变量添加
{DevEco Studio安装路径}/sdk/{SDK版本}/openharmony/toolchains

# macOS/Linux 配置（.bash_profile 或 .zshrc）
export PATH=$TOOL_HOME/sdk/default/openharmony/toolchains:$PATH

# hdc 端口（可选，设为未被占用端口如 7035）
export HDC_SERVER_PORT=7035

验证安装：终端输入 hdc --version

---

三、React Native 工程创建与鸿蒙化配置

3.1 创建 RN 项目

使用指定版本创建新项目（以 0.72.5 为例）：

bash

npx react-native@0.72.5 init MyRNProject --version 0.72.5
cd MyRNProject

3.2 安装鸿蒙适配依赖

bash

# 安装 RNOH 核心库
npm i @react-native-oh/react-native-harmony

# 如遇 bundle-harmony 命令报错，需额外安装
npm install memfs@^4.17.2

3.3 配置 package.json

在 scripts 中新增鸿蒙打包命令：

json

{
  "scripts": {
    "dev": "react-native bundle-harmony --dev"
  }
}

3.4 配置 Metro 打包工具

修改 metro.config.js，添加鸿蒙适配配置：

javascript

const {mergeConfig, getDefaultConfig} = require('@react-native/metro-config');
const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');

const config = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

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

3.5 生成 JS Bundle

bash

npm run dev

成功后会生成 harmony/entry/src/main/resources/rawfile/bundle.harmony.js 和 assets/ 文件夹。

---

四、鸿蒙原生工程集成 RNOH

4.1 在 DevEco Studio 中创建鸿蒙工程

1. 在 RN 项目根目录下新建 harmony 文件夹

2. 用 DevEco Studio 在此目录创建新工程，Compile SDK 选择 API 20

3. 配置签名：File > Project Structure > Signing Configs，勾选 Support HarmonyOS 和 Automatically generate signature，登录华为账号

4.2 安装鸿蒙侧依赖

在 entry 目录下执行：

bash

ohpm i @rnoh/react-native-openharmony

4.3 补充 C++ 层代码

在 entry/src/main/cpp/ 目录下创建 CMakeLists.txt，配置 RNOH 适配层编译：

cmake

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp")

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

add_library(rnoh_app SHARED
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)

target_link_libraries(rnoh_app PUBLIC rnoh)

同时创建 PackageProvider.cpp：

cpp

#include "RNOH/PackageProvider.h"
using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {};
}

4.4 配置 build-profile.json5

在 entry/build-profile.json5 中添加 externalNativeOptions：

json

{
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": ""
    }
  }
}

4.5 补充 ArkTS 侧代码

将 EntryAbility.ets 继承改为 RNAbility：

typescript

import { RNAbility } from '@rnoh/react-native-openharmony';

export default class EntryAbility extends RNAbility {
  getPagePath() {
    return 'pages/Index';
  }
}

创建 RNPackagesFactory.ets：

typescript

import { RNPackageContext, RNPackage } from '@rnoh/react-native-openharmony/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [];
}

4.6 修改 Index.ets 主页面

在 pages/Index.ets 中加载 RNOH 核心上下文并渲染 RNApp。

---

五、关键环境变量汇总

变量名	值	说明
RNOH_C_API_ARCH	1	启用 CAPI 版本架构，必须配置
HDC_SERVER_PORT	7035（或其他空闲端口）	hdc 调试端口
PATH	含 SDK/toolchains 路径	使 hdc 命令可用
registry（.npmrc）	https://repo.huaweicloud.com/repository/npm/	华为 npm 镜像加速

---

六、常见问题与解决方案

6.1 error: unknown command 'bundle-harmony'

解决方案：手动在 package.json 中添加 "memfs": "^4.17.2" 依赖，重新安装后重试。

6.2 App 启动后没有加载 Bundle

原因：端口映射未成功。执行以下命令：

bash

hdc rport tcp:8081 tcp:8081

6.3 第三方库未生效

原因：node_modules 被覆盖导致 metro 配置失效。检查 node_modules/react-native-harmony/metro.config.js 中 fs.lstatSync 是否已改为 fs.statSync（pnpm 用户需注意）。

6.4 三方库未适配鸿蒙怎么办？

• 纯 JS 库：可直接使用原库

• 含原生代码的库：查阅 RNOH 三方库文档 寻找已适配版本，或寻找替代库

6.5 需要申请白名单吗？

是的。目前 RNOH 相关工具链和 SDK 尚未全面开放，个人开发者需要通过 HarmonyOS 应用开发门户申请白名单成为合作伙伴才能获取完整开发套件。

---

七、写在最后

RNOH 项目仍在快速发展中，华为已承诺持续迭代更新。对于计划将 React Native 应用迁移到鸿蒙生态的开发者，当前最稳妥的路径是：

1. 使用 RN 0.72.5 版本

2. 严格按上述步骤配置环境

3. 参考官方 Gitee 仓库 ohos_react_native 的最新文档

复杂功能（如高性能动画、硬件调用）建议结合 ArkTS 原生开发 实现，以获得最佳性能和兼容性。