从零到一：React Native 应用无缝接入 OpenHarmony 生态的完整实践

随着 OpenHarmony 生态的蓬勃发展，如何将成熟的跨平台开发框架 React Native 与其结合，成为众多开发者关注的焦点。本文将手把手带你完成从零搭建 React Native for OpenHarmony 开发环境的全过程，打通 JavaScript 与 ArkTS 的桥梁，让你能快速将现有 RN 应用扩展到鸿蒙平台，实现一次开发，多端部署的愿景。

一、项目初始化与环境准备

万事开头难，一个良好的开端是成功的一半。搭建环境的第一步，是创建一个规范的 React Native 项目，并为其注入 OpenHarmony 的“基因”。

首先，我们需要规避一个常见的“坑”——Windows 系统的路径长度限制。 建议在系统盘根目录（例如 C:\）下创建一个简洁的工作文件夹，例如命名为 RNProject。这样可以确保后续的依赖安装和编译过程不会因路径过长而失败。

进入该文件夹后，打开命令行终端。你可以通过按住 Shift 键并右键选择“在此处打开 PowerShell 窗口”，或直接在地址栏输入 cmd 并回车。

接下来，初始化 React Native 项目。为了确保与 OpenHarmony 社区提供的桥接库最佳兼容，我们选择 React Native 0.72.5 这个特定版本作为基线。执行以下命令创建项目：

npx react-native@0.72.5 init AtomGitNews --version 0.72.5

命令执行成功后，终端会输出类似 Your project has been successfully created! 的提示，并列出项目结构。此时，一个标准的 React Native 项目就创建好了，但它还只支持 Android 和 iOS。

技术延伸： 与使用 JavaScript (React Native)、Python (Kivy) 或 Go (Fyne) 进行跨平台开发类似，为 OpenHarmony 适配的关键在于提供一个能与原生系统（此处是 ArkUI）通信的“桥接层”。这正是接下来要安装的 @react-native-oh/react-native-harmony 包的核心作用。

[AFFILIATE_SLOT_1]

二、集成 OpenHarmony 支持与工程鸿蒙化

现在，我们要为这个“纯血”的 React Native 项目安装 OpenHarmony 的“心脏”——官方桥接库。

在项目根目录下，运行以下命令安装核心依赖：

npm i @react-native-oh/react-native-harmony@0.72.90

安装完成后，请务必检查 package.json 文件，确认依赖已正确添加：

"dependencies": {
"@react-native-oh/react-native-harmony": "^0.72.90",
// ... 其他依赖
}

安装好桥接库后，下一步是生成原生的 OpenHarmony 工程骨架。在项目根目录执行鸿蒙化脚本：

⚠️ 关键路径要求：
原生工程必须位于下，这是工具链的约定路径，不可更改。

这个命令会在项目下创建 harmony 目录，里面包含了完整的 OpenHarmony 应用项目结构（如 entry、build-profile.json5 等），为后续在 DevEco Studio 中打开和编译做好了准备。

⚠️ 注意事项： 与配置 Android (Java/Kotlin) 或 iOS (Objective-C/Swift) 原生工程不同，OpenHarmony 工程主要使用 ArkTS 和 C++。因此，我们需要对 React Native 的打包工具 Metro 进行特殊配置，使其能正确处理鸿蒙平台的模块。

三、配置打包器与原生运行时集成

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
);

保存配置后，执行命令生成供 OpenHarmony 应用加载的 JS Bundle：

npm run harmony

此命令会启动 Metro 服务，编译你的 React 代码，并输出 index.bundle 等文件到指定目录，这是连接 JS 逻辑与原生界面的关键产物。

接下来，进入最核心的原生工程配置环节。首先，需要安装 OpenHarmony 侧的 React Native 运行时依赖：

ohpm i @rnoh/react-native-openharmony@0.72.90

然后，我们需要在原生工程中集成 RNOH（React Native for OpenHarmony）运行时框架。这主要通过添加和修改几个关键文件来实现，它们共同构成了 JavaScript 与 ArkTS/C++ 之间的通信桥梁。

C++ 层构建配置 (CMakeLists.txt)： 用于引入 RNOH 的 C++ 原生模块。
原生模块注册入口 (PackageProvider.cpp)： 以 C++ 编写，负责注册那些需要高性能或直接调用系统 API 的模块。
ArkTS 侧模块工厂 (RNPackagesFactory.ets)： 以 TypeScript 风格的 ArkTS 编写，管理 JS 层可调用的模块。

以下是关键的 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)

以及原生模块注册入口的 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 {};
  }

ArkTS 侧的模块工厂文件内容如下：

import { RNPackageContext, RNPackage } from '@rnoh/react-native-openharmony/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [];
}

[AFFILIATE_SLOT_2]

四、修改应用入口与最终运行

最后，也是最关键的一步，是修改 OpenHarmony 应用的 Ability 入口，使其能够承载 React Native 视图。

找到并打开 EntryAbility.ets 文件，将其内容替换为以下代码。核心变化是让入口 Ability 继承自 RNOHAbility 而不是普通的 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');
}
}

✅ 大功告成！ 至此，所有配置工作已完成。现在，你可以在 DevEco Studio 中打开项目下的 harmony 目录（AtomGitNews/harmony）。

选择一个 OpenHarmony 模拟器或连接真机，点击运行按钮。如果一切顺利，你将看到 React Native 经典的欢迎界面在 OpenHarmony 设备上成功渲染！这标志着从 JavaScript 到 ArkUI 的整个渲染链路已经完全打通。

总结与展望

本文详细演示了将 React Native 应用移植到 OpenHarmony 平台的完整流程。我们不仅完成了项目初始化、依赖集成、打包配置，更深入到了 C++ 与 ArkTS 双端的原生运行时集成，涵盖了：

环境规范化与特定版本 RN 项目的创建。
安装鸿蒙桥接库与生成原生工程骨架。
配置 Metro 打包器以输出鸿蒙可识别的 Bundle。
集成 RNOH 运行时，编写 C++ 及 ArkTS 桥接代码。
修改应用入口，最终在设备上运行验证。

这套方案为拥有大量 React Native 代码资产的团队快速进入 OpenHarmony 生态提供了清晰的路径。未来，随着 @react-native-oh 库的持续完善，更多 React Native 生态库将被兼容，开发者可以更从容地应对多端开发的挑战，在 JavaScript 的世界里构建繁荣的鸿蒙应用。

技术栈版本参考：
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+

⏳ 首次构建耗时较长：
由于需编译 C++ 代码、打包 JS Bundle、生成 HAP 文件，首次运行可能需要 8–15 分钟，请耐心等待。

AtomGitNews/harmony/@react-native-oh

发表于 2026-02-25 15:44 jzssuanfa 阅读(186) 评论(0) 收藏举报

刷新页面返回顶部