React Native → HarmonyOS环境搭建与项目初始化

徐建国

发布于 2025-12-31 10:38:27

620

文章被收录于专栏：个人路线个人路线

环境搭建与项目初始化（React Native → HarmonyOS）

⚙️ 配置 RNOH 开发环境（macOS 版本）

✅ 目标：完成 DevEco Studio 安装、HDC 环境配置、CAPI 变量配置与 npm 源优化。
🧪 验证：文末提供快速校验步骤，确保各项配置生效。

🧰 步骤一：安装 DevEco Studio

从官网[1]下载并安装最新版本 DevEco Studio。
💡 建议：安装完成后先启动一次应用，以便系统正确注册相关路径与权限。

🔌 步骤二：配置 HDC 环境

打开终端，执行以下命令，打开.bash_profile或者.zshrc文件。

open ~/.bash_profile # 如果没有该文件，先执行vi ~/.bash_profile
# 或者
open ~/.zshrc # 如果没有该文件，先执行vi ～/.zshrc

在文件中输入以下内容，在 PATH 路径下添加 HDC 工具路径，并设置HDC_SERVER_PORT端口：

export PATH="/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH" # 按照实际 SDK 安装路径配置，需要选择{显示包内容}

# HDC端口变量名为：HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如7035
HDC_SERVER_PORT=7035
launchctl setenv HDC_SERVER_PORT $HDC_SERVER_PORT
export HDC_SERVER_PORT

执行以下命令，使环境变量生效：

source ~/.bash_profile
# 或者
source ~/.zshrc

💡 提示： /Applications/DevEco-Studio.app/... 路径可能因安装位置不同而变化。若通过 Finder 定位，右键 DevEco Studio → 显示包内容（Show Package Contents），再逐级进入。

🧩 步骤三：配置 CAPI 版本环境变量

当前 RN 框架提供的 Demo 工程默认为 CAPI 版本，需设置环境变量RNOH_C_API_ARCH = 1。

打开终端，执行以下命令，打开.bash_profile或者.zshrc文件。

open ~/.bash_profile # 如果没有该文件，先执行vi ~/.bash_profile
# 或者
open ~/.zshrc # 如果没有该文件，先执行vi ～/.zshrc

在打开的文件末尾增加以下行：

export RNOH_C_API_ARCH=1

执行以下命令，使环境变量生效：

source ~/.bash_profile
# 或者
source ~/.zshrc

🧪 验证：在终端输入以下命令，输出结果为 1 则设置成功。

echo $RNOH_C_API_ARCH

💡 提示：如果在配置环境变量时 DevEco Studio 已开启，务必在环境变量配置完成后重启 DevEco Studio，以便于工具能够检测到环境变量。

🚀 步骤四：编辑用户级 `.npmrc` 配置文件

open ~/.npmrc # 如果没有该文件，先执行vi ~/.npmrc

为了加速 npm 包下载，可配置镜像源，.npmrc配置文件内容如下：

strict-ssl=false
sslVerify=false
registry=https://repo.huaweicloud.com/repository/npm/

⚠️ 变更后请执行以下命令清理缓存，确保新的 registry 生效：

npm cache clean --force

🔍 快速校验清单

🧰 HDC 工具是否可用：运行 hdc --version，应能正确输出版本号。
🔌 端口环境变量：执行 echo $HDC_SERVER_PORT，确认端口值（示例为 7035）。
🧩 CAPI 架构变量：执行 echo $RNOH_C_API_ARCH，输出应为 1。
🚀 NPM 源：执行 npm config get registry，应显示 https://repo.huaweicloud.com/repository/npm/。

📐 使用约束

若需自定义 CMakeLists.txt，请将 so 命名为 rnoh_app。

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

🚀 创建 React Native 工程

本章节将带你完成 React Native 工程的初始化、安装鸿蒙依赖并生成 bundle。

🎯 目标：创建工程 → 安装鸿蒙化依赖 → 生成 Harmony bundle
🧭 适用版本：React Native for OpenHarmony 仅支持 0.72.5

🆕 创建新项目

可选择一个目录，使用 React Native 内置 CLI 创建一个名为“RnohSample”的新项目。命令无需预装 CLI，直接通过 npx 使用。

npx react-native@0.72.5 init RnohSample --version 0.72.5 [--skip-install]

💡 提示：在 macOS 上初始化时会尝试下载 iOS 依赖，可能耗时较长。可添加 --skip-install 跳过，稍后按需自行安装，不影响鸿蒙项目开发。

image-20250906183149068

📦 安装鸿蒙依赖包并生成 bundle

✅ 前置条件

Node.js 建议使用 LTS（如 16/18），需包含 npx
NPM 8+（或使用 PNPM/Yarn 并据此调整命令）

⬇️ 下载并安装鸿蒙化依赖

在 RnohSample 目录下，先在 package.json 的 scripts 中新增 OpenHarmony 的命令：

{
  // ...
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "lint": "eslint .",
    "start": "react-native start",
    "test": "jest",
    "dev": "react-native bundle-harmony --dev"
  },
  // ...
}

然后安装鸿蒙依赖：

npm i @react-native-oh/react-native-harmony@x.x.x

ℹ️ 说明：@x.x.x 指定版本号，不指定则默认安装最新版本。示例：@0.72.86。

image-20250908163815456

🧱 运行命令并生成 bundle

打开 RnohSample/metro.config.js，添加 OpenHarmony 的适配配置。配置项说明可参考「TODO metro 配置文件」，示例：

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
// 新增OpenHarmony配置
const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
/**
 * Metro configuration
 * https://facebook.github.io/metro/docs/configuration
 *
 * @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);

在 RnohSample 目录下运行生成 bundle 的命令。成功后，会在 RnohSample/harmony/entry/src/main/resources/rawfile 目录下生成 bundle.harmony.js 和 assets 文件夹（若未使用本地图片则无 assets）。

npm run dev

image-20250908154018408

✅ 验证：确认 rawfile 目录下生成的 bundle.harmony.js 文件存在；如无生成，请检查 metro.config.js 是否已按示例配置。

🏗️ 创建鸿蒙工程

本章节主要介绍鸿蒙工程的创建，并加载 React Native 相关的依赖包和 bundle 包，最终完成鸿蒙工程的运行的过程。

你也可以按照本节中的操作一步一步完成环境的搭建，也可以直接使用 MyApplicationReplace 压缩包[2] 文件夹中的对应文件进行一一替换，修改版本信息并运行。

新建工程中集成 React Native

步骤一：创建鸿蒙项目有两种形式，任选其一。

在Welcome to DevEco Studio窗口，依次点击Projects > Create Project打开新建鸿蒙工程向导。

image-20250908161930906

在已打开工程菜单栏依次点击File > New > Create Project打开新建鸿蒙工程向导。

未命名

步骤二：在打开的新建鸿蒙工程向导，依次点击Application > Empty Ability > Next打开配置工程信息向导。

image-20250908162702219

步骤三：配置鸿蒙工程信息。

image-20250908163139906

添加 React Native 配置

在entry目录下执行以下命令：

ohpm i @rnoh/react-native-openharmony@x.x.x

注意：

指令中@x.x.x 用于指定下载的版本，不指定时默认下载最新版本，当前示例为@0.72.86。

image-20250908165533208

🔧 在原生工程中集成 RNOH

🧩 补充 CPP 侧代码

在RnohExample/entry/src/main目录下新建 cpp 文件。
在 cpp 目录下新增CMakeLists.txt，并将 RNOH 的适配层代码添加到编译构建中生成librnoh_app.so。

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
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)

target_link_libraries(rnoh_app PUBLIC rnoh)

在 cpp 目录下新增PackageProvider.cpp，该文件需要满足以下要求：

需要导入RNOH/PackageProvider;
实现getPackages方法，用于创建三方库或自定义 TurboModule 或 Fabric 的 package 对象。

此处不涉及三方库与自定义 TurboModule 或组件，需要返回空数组。

#include "RNOH/PackageProvider.h"

using namespace rnoh;

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

打开RnohExample/entry/build-profile.json5，将 cpp 中的代码添加到应用工程的编译构建任务中；如果x86_64架构的模拟器上运行应用，需在externalNativeOptions配置中额外添加abiFilters字段，并包含x86_64架构参数，如下所示，abiFilters字段当前被注释，默认仅构建适应于arm64-v8a架构的版本。

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

🧩 补充 ArkTS 侧代码

打开RnohExample/entry/src/main/ets/entryability/EntryAbility.ets，引入并使用RNAbility，该文件需要满足以下的要求：

需要重写getPagePath，返回程序的入口 page。

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

export default class EntryAbility extends RNAbility {
  getPagePath(): string {
    return "pages/Index"
  }
}

如果需要扩展使用对应的生命周期函数
- 请在代码中调用super（由于RNAbility）在生命周期函数中进行了对应的操作，因此建议使用super以确保原有功能不丢失。
- 需确保函数的参数列表与父类保持兼容。
- 建议添加override关键字，以提升代码可读性并增强编译器检查。

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

exportdefaultclass EntryAbility extends RNAbility {

  getPagePath(): string {
    return"pages/Index"
  }

  override onCreate(want: Want): void {
    super.onCreate(want);
    this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'EntryAbility onCreate');
  }
}

在RnohExample/entry/src/main/ets目录下新增RNPackagesFactory.ets，该文件需要满足以下要求：

在@rnoh/react-native-openharmony导入RNPackageContext和RNOHPackage；
在文件中导出createRNPackages方法，用于创建三方库或自定义 TurboModule、Fabric 的 package 对象。

此处不涉及三方库与自定义 TurboModule 或组件，需要返回空数组。

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

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

打开RnohExample/entry/src/main/ets/pages/Index.ets，添加 RNOH 的使用代码，修改后如下：

⚠️ 注意：RNApp 的参数 appKey 需要与 RN 工程中 AppRegistry.registerComponent 注册的 appName 保持一致，否则会导致白屏。

import {
  AnyJSBundleProvider,
  ComponentBuilderContext,
  FileJSBundleProvider,
  MetroJSBundleProvider,
  ResourceJSBundleProvider,
  RNApp,
  RNOHErrorDialog,
  RNOHLogger,
  TraceJSBundleProviderDecorator,
  RNOHCoreContext
} from'@rnoh/react-native-openharmony';
import { createRNPackages } from'../RNPackagesFactory';

@Builder
exportfunction buildCustomRNComponent(ctx: ComponentBuilderContext) {}

const wrappedCustomRNComponentBuilder = wrapBuilder(buildCustomRNComponent)

@Entry
@Component
struct Index {
@StorageLink('RNOHCoreContext') private rnohCoreContext: RNOHCoreContext | undefined = undefined
@State shouldShow: boolean = false
private logger!: RNOHLogger

  aboutToAppear() {
    this.logger = this.rnohCoreContext!.logger.clone("Index")
    const stopTracing = this.logger.clone("aboutToAppear").startTracing();

    this.shouldShow = true
    stopTracing();
  }

  onBackPress(): boolean | undefined {
    // NOTE: this is required since `Ability`'s `onBackPressed` function always
    // terminates or puts the app in the background, but we want Ark to ignore it completely
    // when handled by RN
    this.rnohCoreContext!.dispatchBackPress()
    returntrue
  }

  build() {
    Column() {
      if (this.rnohCoreContext && this.shouldShow) {
        if (this.rnohCoreContext?.isDebugModeEnabled) {
          RNOHErrorDialog({ ctx: this.rnohCoreContext })
        }
        RNApp({
          rnInstanceConfig: {
            createRNPackages,
            enableNDKTextMeasuring: true, // 该项必须为true，用于开启NDK文本测算
            enableBackgroundExecutor: false,
            enableCAPIArchitecture: true, // 该项必须为true，用于开启CAPI
            arkTsComponentNames: []
          },
          initialProps: { "foo": "bar" } as Record<string, string>,
          appKey: "RnohSample",
          wrappedCustomRNComponentBuilder: wrappedCustomRNComponentBuilder,
          onSetUp: (rnInstance) => {
            rnInstance.enableFeatureFlag("ENABLE_RN_INSTANCE_CLEAN_UP")
          },
          jsBundleProvider: new TraceJSBundleProviderDecorator(
            new AnyJSBundleProvider([
              new MetroJSBundleProvider(),
              // NOTE: to load the bundle from file, place it in
              // `/data/app/el2/100/base/com.rnoh.tester/files/bundle.harmony.js`
              // on your device. The path mismatch is due to app sandboxing on OpenHarmony
              new FileJSBundleProvider('/data/storage/el2/base/files/bundle.harmony.js'),
              new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'hermes_bundle.hbc'),
              new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js')
            ]),
            this.rnohCoreContext.logger),
        })
      }
    }
    .height('100%')
    .width('100%')
  }
}

📁 本地加载 bundle 包

将[创建 React Native 工程]( "创建 React Native 工程")章节中执行npm run dev后的harmony/entry/src/main/resources/rawfile目录下的bundle文件和assets图片拷贝到鸿蒙工程entry/src/main/resources/rawfile路径下。

image-20251110160312319

启动并运行工程

使用 DevEco Studio 运行 RnohExample 工程，执行完成后，控制台如图所示：

🎉 恭喜：工程成功启动后，您将看到 RN 应用在鸿蒙环境中运行的日志输出与界面展示。

image-20250908193915068

image-20250908193752588

参考资料

[1]

官网: https://developer.huawei.com/consumer/cn/deveco-studio/

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-12-24，如有侵权请联系 cloudcommunity@tencent.com 删除

配置

本文分享自大前端之旅微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度