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

2025-12-04 14:55:41 分类：react native 热度：981 评论： 0

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

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

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

🧰 步骤一：安装 DevEco Studio

  • 从官网下载并安装最新版本 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.***/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.***/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 跳过，稍后按需自行安装，不影响鸿蒙项目开发。

📦 安装鸿蒙依赖包并生成 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。

🧱 运行命令并生成 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

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

🏗️ 创建鸿蒙工程

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

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

新建工程中集成React Native

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

  • 在Wel***e to DevEco Studio窗口，依次点击Projects > Create Project打开新建鸿蒙工程向导。
  • 在已打开工程菜单栏依次点击File > New > Create Project打开新建鸿蒙工程向导。

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

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

添加React Native配置

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

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

注意：

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

🔧 在原生工程中集成 RNOH

🧩 补充 CPP 侧代码
  1. 在RnohExample/entry/src/main目录下新建cpp文件。
  2. 在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-***mand-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
add_***pile_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)
  1. 在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 {};
}
  1. 打开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';

export default class 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.register***ponent 注册的 appName 保持一致，否则会导致白屏。

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

@Builder
export function buildCustomRN***ponent(ctx: ***ponentBuilderContext) {}

const wrappedCustomRN***ponentBuilder = wrapBuilder(buildCustomRN***ponent)

@Entry
@***ponent
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 ***pletely
    // when handled by RN
    this.rnohCoreContext!.dispatchBackPress()
    return true
  }

  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
            arkTs***ponentNames: []
          },
          initialProps: { "foo": "bar" } as Record<string, string>,
          appKey: "RnohSample",
          wrappedCustomRN***ponentBuilder: wrappedCustomRN***ponentBuilder,
          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/***.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工程章节中执行npm run dev后的harmony/entry/src/main/resources/rawfile目录下的bundle文件和assets图片拷贝到鸿蒙工程entry/src/main/resources/rawfile路径下。

启动并运行工程

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

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

转载请说明出处内容投诉
CSS教程网 » 环境搭建与项目初始化（React Native → HarmonyOS）
努力！奋斗已认证

努力！奋斗已认证

分享到：

发表评论

欢迎 访客 发表评论

一个令你着迷的主题！

查看演示 官网购买