React Native for OpenHarmony 开发环境搭建全指南

开发环境搭建全指南

- [一、创建 React Native 项目并集成 OpenHarmony 支持](#一、创建 React Native 项目并集成 OpenHarmony 支持)
- - [1. 新建项目目录](#1. 新建项目目录)
  - [2. 进入命令行环境](#2. 进入命令行环境)
  - [3. 初始化 React Native 项目](#3. 初始化 React Native 项目)
  - [4. 修改项目配置以支持鸿蒙](#4. 修改项目配置以支持鸿蒙)
  - [5. 安装 OpenHarmony 专用依赖包](#5. 安装 OpenHarmony 专用依赖包)
  - [6. 创建原生 OpenHarmony 工程](#6. 创建原生 OpenHarmony 工程)
  - [7. 配置 Metro 打包器以支持 Harmony](#7. 配置 Metro 打包器以支持 Harmony)
- [二、配置原生 OpenHarmony 工程](#二、配置原生 OpenHarmony 工程)
- - [1. 安装 RNOH 原生依赖](#1. 安装 RNOH 原生依赖)
  - [2. 集成 RNOH 运行时框架](#2. 集成 RNOH 运行时框架)
  - - [(1) `CMakeLists.txt` ------ C++ 构建配置](#(1) CMakeLists.txt —— C++ 构建配置)
    - [(2) `PackageProvider.cpp` ------ 原生模块注册入口（C++）](#(2) PackageProvider.cpp —— 原生模块注册入口（C++）)
    - [(3) `RNPackagesFactory.ets` ------ ArkTS 侧模块工厂](#(3) RNPackagesFactory.ets —— ArkTS 侧模块工厂)
    - [(4) `EntryAbility.ets` ------ 应用主入口（关键修改）](#(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 的新项目：

bash 复制代码

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 的核心桥接库：

bash 复制代码

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

✅ 版本对齐原则 ：
0.72.90 中的主版本号 0.72 必须与 React Native 主版本严格一致，次版本号 .90 表示这是专为 OpenHarmony 适配的发行版。

安装完成后，package.json 的 dependencies 字段将自动新增该依赖：

请确认其已正确添加：

json 复制代码

"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。

将以下代码完整替换原文件内容：

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：

bash 复制代码

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 运行时：

bash 复制代码

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++ 构建配置

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_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++）

cpp 复制代码

//
// 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<MyCustomPackage>()。

(3) `RNPackagesFactory.ets` ------ ArkTS 侧模块工厂

ts 复制代码

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：

ts 复制代码

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

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 ------ 应用主入口（关键修改）

三、运行项目

总结

(1) `CMakeLists.txt` ------ C++ 构建配置

(2) `PackageProvider.cpp` ------ 原生模块注册入口（C++）

(3) `RNPackagesFactory.ets` ------ ArkTS 侧模块工厂

(4) `EntryAbility.ets` ------ 应用主入口（关键修改）