React Native for OpenHarmony 开发环境搭建全指南
开发环境搭建全指南
- 一、创建 React Native 项目并集成 OpenHarmony 支持
- 1. 新建项目目录
- 2. 进入命令行环境
- 3. 初始化 React Native 项目
- 4. 修改项目配置以支持鸿蒙
- 5. 安装 OpenHarmony 专用依赖包
- 6. 创建原生 OpenHarmony 工程
- 7. 配置 Metro 打包器以支持 Harmony
- 二、配置原生 OpenHarmony 工程
- 1. 安装 RNOH 原生依赖
- 2. 集成 RNOH 运行时框架
- (1) `CMakeLists.txt` —— C++ 构建配置
- (2) `PackageProvider.cpp` —— 原生模块注册入口（C++）
- (3) `RNPackagesFactory.ets` —— ArkTS 侧模块工厂
- (4) `EntryAbility.ets` —— 应用主入口（关键修改）
- 三、运行项目
- 总结
特别注意事项：
由于 Windows 系统对文件路径长度的限制（MAX_PATH = 260 字符），项目必须创建在盘符根目录下（如C:RNProject），否则在依赖安装或构建过程中极有可能因路径过长而报错。本文所有操作均在根目录下完成，如下图所示：
一、创建 React Native 项目并集成 OpenHarmony 支持
1. 新建项目目录
首先，在系统盘根目录（例如 C:）下新建一个工作文件夹，命名为 RNProject。该命名简洁且层级最浅，可有效规避 Windows 路径长度限制问题。
2. 进入命令行环境
在 RNProject 文件夹内，按住 Shift 键并右键空白处，选择“在此处打开 PowerShell 窗口”或直接在地址栏输入 cmd 并回车，进入命令行终端。
3. 初始化 React Native 项目
为确保与 OpenHarmony 社区生态兼容，我们使用 React Native 0.72.5 版本作为基线。执行以下命令创建名为 AtomGitNews 的新项目：
npx react-native@0.72.5 init AtomGitNews --version 0.72.5
💡 说明：
npx可避免全局安装 RN CLI，保证版本一致性；- 显式指定
--version是为了锁定与@react-native-oh/react-native-harmony兼容的 RN 核心版本。
当终端输出类似 Your project has been successfully created! 的提示，并列出项目结构时，表明项目已成功初始化。
4. 修改项目配置以支持鸿蒙
使用 VS Code 或 Trae 打开 AtomGitNews 项目。此时项目仅支持 Android/iOS，需手动注入 OpenHarmony 构建能力。
5. 安装 OpenHarmony 专用依赖包
在项目根目录的终端中，执行以下命令安装 React Native for OpenHarmony 的核心桥接库：
npm i @react-native-oh/react-native-harmony@0.72.90
✅ 版本对齐原则：
0.72.90中的主版本号0.72必须与 React Native 主版本严格一致，次版本号.90表示这是专为 OpenHarmony 适配的发行版。
安装完成后，package.json 的 dependencies 字段将自动新增该依赖：
请确认其已正确添加：
"dependencies": {
"@react-native-oh/react-native-harmony": "^0.72.90",
// ... 其他依赖
}
6. 创建原生 OpenHarmony 工程
在 AtomGitNews 目录下，执行鸿蒙化脚本以生成原生工程骨架。该步骤会创建 harmony/ 子目录，包含完整的 OpenHarmony 项目结构（entry、oh_modules 等）。
⚠️ 关键路径要求：
原生工程必须位于AtomGitNews/harmony/下，这是@react-native-oh工具链的约定路径，不可更改。
7. 配置 Metro 打包器以支持 Harmony
React Native 使用 Metro 作为 JavaScript 打包工具。为支持 OpenHarmony 的模块解析与资源处理，需重写 metro.config.js。
将以下代码完整替换原文件内容：
const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const {createHarmonyMetroConfig} = require("@react-native-oh/react-native-harmony/metro.config");
/**
* Metro configuration for OpenHarmony
* Integrates RNOH-specific resolver and transformer rules.
*
* @type {import('metro-config').MetroConfig}
*/
const config = {
transformer: {
getTransformOptions: async () => ({
transform: {
experimentalImportSupport: false,
inlineRequires: true
}
})
}
};
module.exports = mergeConfig(
getDefaultConfig(__dirname),
createHarmonyMetroConfig({
reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony'
}),
config
);
🔧 配置解析：
createHarmonyMetroConfig注入了 OpenHarmony 专属的模块解析规则（如.ets文件处理）；mergeConfig确保默认配置、鸿蒙配置与自定义配置正确合并。
保存后，在终端执行以下命令生成 JS Bundle：
npm run harmony
该命令会：
- 启动 Metro 服务；
- 编译 JS/TS 代码；
- 输出
index.harmony.bundle和index.harmony.bundle.map到harmony/entry/src/main/resources/rawfile/目录。
二、配置原生 OpenHarmony 工程
1. 安装 RNOH 原生依赖
进入 AtomGitNews/harmony/entry 目录，在此打开终端，执行以下命令安装 OpenHarmony 侧的 React Native 运行时：
ohpm i @rnoh/react-native-openharmony@0.72.90
📦 ohpm 说明：
ohpm（OpenHarmony Package Manager）是 OpenHarmony 官方包管理工具，用于管理 ArkTS/C++ 原生依赖，与 npm 互补而非替代。
2. 集成 RNOH 运行时框架
为使 OpenHarmony 应用能够加载并运行 React Native Bundle，需在原生工程中集成 RNOH（React Native for OpenHarmony）运行时。只需添加以下三个关键文件：
(1) CMakeLists.txt —— C++ 构建配置
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_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp")
set(RNOH_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/generated")
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
add_compile_definitions(WITH_HITRACE_SYSTRACE)
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_subdirectory("${RNOH_CPP_DIR}" ./rn)
add_library(rnoh_app SHARED
"${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp" "./PackageProvider.cpp")
target_link_libraries(rnoh_app PUBLIC rnoh)
🔗 作用：
此文件配置 CMake 将 RNOH 的 C++ 核心库（如 JS 引擎绑定、UI 桥接）编译进应用，并链接 NAPI（Native API）接口。
(2) PackageProvider.cpp —— 原生模块注册入口（C++）
//
// Created on 2026/1/29.
//
// Node APIs are not fully supported. To solve the compilation error of the interface cannot be found,
// please include "napi/native_api.h".
#include "RNOH/PackageProvider.h"
using namespace rnoh;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
return {};
}
🧩 扩展点：
若需接入自定义原生模块（如蓝牙、传感器），可在此返回std::make_shared。()
(3) RNPackagesFactory.ets —— ArkTS 侧模块工厂
import { RNPackageContext, RNPackage } from '@rnoh/react-native-openharmony/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [];
}
🌉 作用：
该文件是 ArkTS 与 React Native 模块系统的对接点，目前为空数组，表示暂无额外 TS 模块。
(4) EntryAbility.ets —— 应用主入口（关键修改）
将原 EntryAbility.ets 替换为以下代码，使其继承 RNAbility 而非普通 UIAbility：
import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { RNAbility } from '@rnoh/react-native-openharmony';
const DOMAIN = 0x0000;
export default class EntryAbility extends RNAbility {
protected getPagePath(): string {
return "pages/Index"
}
override onCreate(want: Want): void {
super.onCreate(want);
try {
this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
} catch (err) {
hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
}
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
}
onDestroy(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
return;
}
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
});
}
onWindowStageDestroy(): void {
// Main window is destroyed, release UI related resources
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
}
onForeground(): void {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
}
onBackground(): void {
// Ability has back to background
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
}
}
🚀 核心变更：
- 继承
RNAbility后，应用启动时会自动加载rawfile/index.harmony.bundle；getPagePath()返回 ArkTS 页面路径，用于混合开发场景（纯 RN 应用可忽略）。
三、运行项目
完成上述所有配置后，即可在 DevEco Studio 中打开 AtomGitNews/harmony 目录，选择 OpenHarmony 模拟器或真机进行部署。
⏳ 首次构建耗时较长：
由于需编译 C++ 代码、打包 JS Bundle、生成 HAP 文件，首次运行可能需要 8–15 分钟，请耐心等待。
当应用成功启动并显示 React Native 默认欢迎页面时，表明 React Native for OpenHarmony 环境已完全打通！
总结
本文完整演示了如何从零搭建一个 React Native + OpenHarmony 的开发环境，并成功运行首个跨平台应用。整个流程涵盖了：
- 项目初始化与路径规范；
- JS 层鸿蒙化依赖集成；
- Metro 打包器配置；
- 原生工程生成与 RNOH 运行时集成；
- C++/ArkTS 双端桥接配置。
该方案为开发者提供了在 OpenHarmony 生态中复用 React Native 技术栈的可行路径，尤其适合已有 RN 项目的团队快速迁移至鸿蒙平台。
技术栈版本：
- React Native: 0.72.5
- @react-native-oh/react-native-harmony: 0.72.90
- OpenHarmony SDK: API 20(6.0+)
- DevEco Studio: 6.0.0+
参考文档：https://blog.csdn.net/zl392321162/article/details/156641198
