Windows平台ReactNative鸿蒙开发环境搭建指南

React Native for OpenHarmony（简称RNOH）是React Native针对鸿蒙系统的适配版本，让开发者可以用熟悉的React技术栈开发鸿蒙应用。本文详细介绍在Windows平台搭建RNOH开发环境的完整流程，以及常见问题的解决方案。

2301_81152266

394人浏览 · 2026-02-03 21:37:48

2301_81152266 · 2026-02-03 21:37:48 发布

Windows平台React Native鸿蒙开发环境搭建指南

在这里插入图片描述

前言：React Native for OpenHarmony（简称RNOH）是React Native针对鸿蒙系统的适配版本，让开发者可以用熟悉的React技术栈开发鸿蒙应用。本文详细介绍在Windows平台搭建RNOH开发环境的完整流程，以及常见问题的解决方案。

一、环境准备

在开始之前，请确保已安装以下基础软件：

软件	版本要求	用途
Node.js	16+	JavaScript运行环境
DevEco Studio	6.0+	鸿蒙官方IDE
Git	最新版	版本控制工具
VS Code	可选	代码编辑器

二、环境变量配置

2.1 配置HDC工具路径

HDC（HarmonyOS Device Connector）是鸿蒙设备调试工具。

找到HDC工具位置，通常在：

{DevEco安装目录}\sdk\default\openharmony\toolchains

添加到系统PATH环境变量：
- 右键「开始」→「系统」→「高级系统设置」→「环境变量」
- 在「系统变量」中找到Path，点击「编辑」→「新建」
- 添加上述toolchains路径

2.2 配置HDC端口

在「系统变量」区域点击「新建」：

变量名：HDC_SERVER_PORT
变量值：7035

2.3 配置CAPI架构

RNOH当前使用CAPI架构，需要设置环境变量：

变量名：RNOH_C_API_ARCH
变量值：1

2.4 配置npm镜像源（推荐）

创建或编辑C:\Users\{你的用户名}\.npmrc文件：

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

执行命令清理缓存：

npm cache clean --force

重要提示：配置环境变量后必须重启终端或重启电脑才能生效！

三、创建React Native项目

3.1 初始化RN工程

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

注意：当前RNOH仅支持RN 0.72.5版本

3.2 安装鸿蒙适配包

进入项目目录：

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

3.3 配置package.json

在scripts中添加鸿蒙构建命令：

{
  "scripts": {
    "start": "react-native start",
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "harmony": "react-native bundle-harmony --dev"
  }
}

3.4 配置Metro打包工具

修改metro.config.js：

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const {createHarmonyMetroConfig} = require("@react-native-oh/react-native-harmony/metro.config");

const config = {
    transformer: {
        getTransformOptions: async () => ({
            transform: {
                experimentalImportSupport: false,
                inlineRequires: true,
            },
        }),
    }
};

module.exports = mergeConfig(
    getDefaultConfig(__dirname),
    createHarmonyMetroConfig({
        reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
    }),
    config
);

四、创建鸿蒙工程

4.1 新建Empty Ability项目

打开DevEco Studio，点击「Create Project」
选择「Empty Ability」模板
关键配置：将工程存储位置设为RN项目根目录下的harmony文件夹

例如：D:\Projects\MyRnApp\harmony

4.2 安装鸿蒙侧依赖

在entry目录下打开终端：

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

五、配置鸿蒙原生代码

5.1 CPP侧配置

创建CMakeLists.txt

在entry/src/main/cpp目录下创建CMakeLists.txt：

cmake_minimum_required(VERSION 3.4.1)
project(rnapp)

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)

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)

创建PackageProvider.cpp

#include "RNOH/PackageProvider.h"
#include <vector>

using namespace rnoh;

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

配置build-profile.json5

{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": "",
      "abiFilters": ["arm64-v8a", "x86_64"]
    }
  }
}

5.2 ArkTS侧配置

修改EntryAbility.ets

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

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

  override onCreate(want: Want): void {
    super.onCreate(want);
  }
}

创建RNPackagesFactory.ets

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

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

修改Index.ets

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

@Builder
export function 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")
    this.shouldShow = true
  }

  onBackPress(): boolean | undefined {
    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,
            enableBackgroundExecutor: false,
            enableCAPIArchitecture: true,
            arkTsComponentNames: []
          },
          initialProps: { "foo": "bar" } as Record<string, string>,
          appKey: "MyRnApp",
          wrappedCustomRNComponentBuilder: wrappedCustomRNComponentBuilder,
          onSetUp: (rnInstance) => {
            rnInstance.enableFeatureFlag("ENABLE_RN_INSTANCE_CLEAN_UP")
          },
          jsBundleProvider: new TraceJSBundleProviderDecorator(
            new AnyJSBundleProvider([
              new MetroJSBundleProvider(),
              new FileJSBundleProvider('/data/storage/el2/base/files/bundle.harmony.js'),
              new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js')
            ]),
            this.rnohCoreContext.logger),
        })
      }
    }
    .height('100%')
    .width('100%')
  }
}

注意：appKey必须与RN项目中AppRegistry.registerComponent注册的名称一致！

六、生成Bundle并运行

6.1 生成Bundle文件

在RN项目根目录执行：

npm run harmony

生成文件位置：

harmony/entry/src/main/resources/rawfile/bundle.harmony.js
harmony/entry/src/main/resources/rawfile/assets/（如有图片资源）

6.2 配置端口转发（可选）

如需热更新功能：

hdc rport tcp:8081 tcp:8081

6.3 运行应用

在DevEco Studio中点击运行按钮，选择模拟器或真机设备。
在这里插入图片描述

七、常见问题及解决方法

问题1：hdc命令找不到

原因：HDC工具路径未正确添加到PATH环境变量

解决方案：

# 临时解决（重启后失效）
$env:Path += ";C:\Users\{用户名}\AppData\Local\Huawei\Sdk\default\openharmony\toolchains"

# 永久解决：按前文步骤配置系统环境变量

验证配置：

hdc version

问题2：npm install失败或速度慢

原因：网络问题或镜像源未配置

解决方案：

# 清理npm缓存
npm cache clean --force

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或使用华为云镜像
npm config set registry https://repo.huaweicloud.com/repository/npm/

# 重新安装
npm install

问题3：bundle.harmony.js生成失败

原因：Metro配置错误或依赖未安装

解决方案：

检查metro.config.js是否正确配置：

// 确保导出格式正确
module.exports = mergeConfig(
    getDefaultConfig(__dirname),
    createHarmonyMetroConfig({
        reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
    }),
    config
);

手动指定Metro配置：

npx react-native bundle --platform harmony --dev false --entry-file index.js --bundle-output ./bundle.harmony.js --assets-dest ./assets

问题4：应用白屏

原因：appKey不匹配或bundle路径错误

解决方案：

检查index.js中的注册名称：

AppRegistry.registerComponent('MyRnApp', () => App);

确保Index.ets中的appKey一致：

appKey: "MyRnApp"  // 必须与上面注册的名称完全一致

验证bundle文件是否存在：

# 检查文件是否生成
dir harmony\entry\src\main\resources\rawfile\bundle.harmony.js

问题5：编译报错 - 找不到RNOH头文件

原因：CMakeLists.txt路径配置错误

解决方案：

修改CMakeLists.txt，确保路径正确：

# 使用相对路径
set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules/")
set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp/")

# 或使用绝对路径
set(OH_MODULE_DIR "D:/Projects/MyRnApp/harmony/oh_modules/")

同步工程后重新编译。

问题6：CMakeLists.txt中PackageProvider.cpp路径错误

错误提示：

Could not find ./PackageProvider.cpp

解决方案：

使用相对路径：

add_library(rnoh_app SHARED
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
    "${CMAKE_CURRENT_SOURCE_DIR}/PackageProvider.cpp"  # 使用CMAKE_CURRENT_SOURCE_DIR
)

问题7：真机连接失败

原因：USB调试未开启或HDC服务异常

解决方案：

# 查看连接设备
hdc list targets

# 如果没有设备，重启HDC服务
hdc kill
hdc start

# 检查设备USB调试是否开启
# 设置 → 系统和更新 → 开发者选项 → USB调试

问题8：模拟器启动失败

原因：虚拟化未启用或资源不足

解决方案：

检查BIOS虚拟化是否启用（VT-x或AMD-V）
确保有足够内存（建议8GB以上）
在PowerShell中执行：

# 检查Hyper-V状态
Get-ComputerInfo -Property WindowsFeatureHyperV

# 如需启用Hyper-V（以管理员身份）
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

问题9：依赖版本冲突

错误提示：

npm ERR! peer dep missing

解决方案：

使用--legacy-peer-deps参数安装：

npm install @react-native-oh/react-native-harmony@0.72.90 --legacy-peer-deps

或使用--force参数强制安装：

npm install --force

问题10：DevEco Studio无法识别oh_modules

原因：OhPM包未正确安装或索引未更新

解决方案：

# 重新安装ohpm包
cd harmony/entry
ohpm install

# 在DevEco Studio中
# File → Invalidate Caches → Invalidate and Restart

问题11：热更新不生效

原因：端口转发未配置或Metro服务未启动

解决方案：

配置端口转发：

hdc rport tcp:8081 tcp:8081

启动Metro服务：

npm start
# 在Metro界面按 r 键重新加载

检查jsBundleProvider配置：

jsBundleProvider: new TraceJSBundleProviderDecorator(
  new AnyJSBundleProvider([
    new MetroJSBundleProvider(),  // 确保Metro Provider在第一位
    // ...
  ]),
  this.rnohCoreContext.logger)

问题12：enableCAPIArchitecture相关错误

错误提示：

CAPI architecture is not enabled

解决方案：

确认环境变量已设置：

# 在PowerShell中验证
$env:RNOH_C_API_ARCH
# 应输出：1

确认Index.ets中已开启：

rnInstanceConfig: {
  enableCAPIArchitecture: true,  // 必须为true
  // ...
}

问题13：文本显示异常

原因：NDK文本测算未启用

解决方案：

确保Index.ets配置正确：

rnInstanceConfig: {
  enableNDKTextMeasuring: true,  // 必须为true
  // ...
}

八、版本兼容性说明

组件	版本
React Native	0.72.5（必须）
@react-native-oh/react-native-harmony	0.72.90
@rnoh/react-native-openharmony	0.72.90
DevEco Studio	6.0.0+
HarmonyOS SDK	API 20+

九、总结

搭建React Native鸿蒙开发环境主要包含以下核心步骤：

配置环境变量（HDC、CAPI、npm镜像）
创建React Native 0.72.5项目
安装鸿蒙适配包
创建并配置鸿蒙工程
配置CPP和ArkTS代码
生成bundle并运行

遇到问题时，建议按照以下顺序排查：

检查环境变量是否正确配置
验证依赖包版本是否匹配
查看DevEco Studio和Metro的日志输出
使用hdc命令检查设备连接状态

希望本文能帮助开发者快速上手React Native鸿蒙开发！

参考资源：

React Native官方文档：https://reactnative.dev/

HarmonyOS开发者文档：https://developer.huawei.com/consumer/cn/doc/

RNOH GitHub：https://github.com/react-native-oh-library/OPENHARMONY

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net