作者：zifeiyu

React Native / RNOH

React Native 写鸿蒙
配置教程

从空项目到设备运行，按顺序配置 RNOH、bundle 和 DevEco 工程。

最终目标

做完后，你应该有这三个结果：

  • React Native 项目目录，例如 D:\work\AwesomeProject。
  • DevEco Studio 创建的鸿蒙工程，例如 D:\work\MyApplication。
  • 设备或模拟器上能打开页面，页面内容来自 RN 的 AppRegistry.registerComponent。

0. 先确认版本

RNOH 对 React Native、SDK、DevEco、Node 都有版本要求。不要一上来装最新版本，先按你要用的 RNOH release notes 对齐。

本文示例 RN0.72.5
系统工具DevEco Studio + OpenHarmony SDK + hdc + ohpm
关键环境变量RNOH_C_API_ARCH=1

如果你手里的 RNOH 文档指定了别的 RN 版本，以官方版本说明为准，页面里的命令只按同一套版本替换，不要混用。

1. 准备清单

先把环境准备好。这里少一个，后面大概率会报错。

2. 配好 hdc 和环境变量

2.1 让命令行找到 hdc

hdc 是连接鸿蒙设备的工具。打开 DevEco SDK 目录，找到类似下面的目录并加入 Windows Path：

D:\DevEco Studio\sdk\default\openharmony\toolchains

重新打开 PowerShell，执行：

hdc -v
hdc list targets

hdc -v 能输出版本，说明 Path 生效；hdc list targets 看不到设备时，先回 DevEco 检查模拟器或真机连接。

2.2 打开 C-API 架构

RNOH C-API 架构需要这个环境变量。先临时设置，确认没问题再永久写入。

$env:RNOH_C_API_ARCH="1"
echo $env:RNOH_C_API_ARCH

setx RNOH_C_API_ARCH 1

执行 setx 后重新打开 PowerShell，再执行 echo $env:RNOH_C_API_ARCH。看到 1 才算生效。

3. 创建 React Native 项目

在短路径目录下创建项目。路径里不要有中文、空格和太深的嵌套。

Set-Location D:\work
npx react-native@0.72.5 init AwesomeProject --version 0.72.5
Set-Location .\AwesomeProject
npm install

创建完成后先确认普通 RN 项目结构存在：

dir
type package.json

你应该能看到 index.js、package.json、node_modules 等内容。

3.1 安装 RNOH 依赖

进入 RN 项目根目录，安装鸿蒙适配包。下面的 x.x.x 要换成与你的 RNOH release 对应的版本。

Set-Location D:\work\AwesomeProject
npm i @react-native-oh/react-native-harmony@x.x.x

如果你不知道版本号，先查 RNOH release notes。不要从不同教程里抄多个版本混在一起。

4. 配置 Metro 并生成 Harmony bundle

4.1 修改 package.json

在 scripts 里加一个专门生成鸿蒙 bundle 的命令：

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

4.2 修改 metro.config.js

把 Harmony 的 Metro 配置合并进去：

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

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

4.3 生成 bundle

Set-Location D:\work\AwesomeProject
npm run dev

成功后，检查是否生成了 bundle.harmony.js：

dir .\harmony\entry\src\main\resources\rawfile

5. 创建鸿蒙工程并接入 RNOH

  1. 打开 DevEco Studio，选择 File > New > Create Project。
  2. 模板选择 Empty Ability。
  3. 项目名写 MyApplication，目录放在 D:\work\MyApplication。
  4. Compile SDK 选择与你的 RNOH release notes 对应的 API 版本。
  5. 先不要接 RN，直接点 Run 跑一次 Empty Ability。空工程能跑，再继续。

5.1 安装 OpenHarmony 侧依赖

在鸿蒙工程的 entry 目录执行：

Set-Location D:\work\MyApplication\entry
ohpm i @rnoh/react-native-openharmony@x.x.x

x.x.x 同样要按 RNOH release notes 对齐。安装后等 DevEco 的 SyncData 完成，再编译。

5.2 放入 bundle

把 RN 项目生成的 bundle.harmony.js 复制到鸿蒙工程的 rawfile 目录：

D:\work\MyApplication\entry\src\main\resources\rawfile\bundle.harmony.js

5.3 接入口代码

RNOH 的接入代码会随版本变化。最稳的做法是打开你当前版本的官方 Sample，把下面几处逐项对齐：

Ability 基类RNAbility
页面组件RNApp
包注册createRNPackages
bundle 来源ResourceJSBundleProvider
应用名appKey === AppRegistry.registerComponent 的名字

第一次接入时不要同时加第三方库。先让官方最小示例跑起来，再一点点加你的业务代码。

6. 运行验证

  1. 重新打开 PowerShell，确认 echo $env:RNOH_C_API_ARCH 输出 1。
  2. 执行 hdc list targets，确认有设备 ID。
  3. DevEco Studio 里点击 Sync and Refresh Project。
  4. 点击 Run。第一次会编译 C++，时间比较久，先等完整日志。
  5. 页面能显示 RN 内容后，再考虑 Metro 调试、热更新、第三方库。

7. 常见报错

hdc 找不到

检查 toolchains 是否加入 Path。改完环境变量要重新打开终端。

设备列表为空

先在 DevEco 里确认模拟器或真机在线，再执行 hdc list targets。

bundle 找不到

重新执行 npm run dev，确认 bundle.harmony.js 已复制到 rawfile。

白屏

先查 appKey 是否等于 AppRegistry.registerComponent 注册的名字。

ohpm 依赖缺失

等 DevEco SyncData 完成。必要时删除 oh_modules 后重新 ohpm install。

C++ 编译慢

RNOH 首次编译耗时长。先看完整日志，不要看到卡住就强制结束。

资料