Windows 11 OpenHarmony版React Native开发环境搭建完整指南

📝 适合人群 ：React Native 开发者、HarmonyOS 应用开发者

⏱️ 预计时间 ：2-3 小时（包含下载和配置时间）

🎯 学习目标：成功搭建 React Native for OpenHarmony 开发环境

📖 什么是 React Native for OpenHarmony？

React Native 是 Facebook（Meta）开发的跨平台移动应用开发框架，可以用 JavaScript 和 React 开发原生应用。

React Native for OpenHarmony 是 React Native 针对 OpenHarmony/HarmonyOS 系统的适配版本，让你可以用 React Native 开发 HarmonyOS 应用。

主要优势：

✅ 一套代码，多平台运行（Android、iOS、HarmonyOS）
✅ 使用熟悉的 React 和 JavaScript 技术栈
✅ 接近原生应用的性能
✅ 热重载，快速开发调试

🖥️ 测试环境

本文档基于以下环境进行测试：

💻 设备规格 ：
- 处理器：13th Gen Intel® Core™ i5-13500H (3.19 GHz)
- 内存：16.0 GB
- 系统类型：64 位操作系统, 基于 x64 的处理器
🪟 Windows规格 ：
- 版本：Windows 11 家庭版
- 版本号：25H2

📋 前置条件

在开始搭建环境之前，请确保已经完成以下软件的安装：

✅ Windows 11 安装 Visual Studio Code 完整指南 - 代码编辑器
✅ Windows 11 安装 Git 完整指南 - 版本控制工具
✅ Windows 11 安装 DevEco Studio 完整指南 - HarmonyOS/OpenHarmony开发IDE

⚠️ 重要提示：

请按照顺序完成前置软件的安装，特别是 DevEco Studio 和 Git，它们是必需的

确保 DevEco Studio 已下载并配置好 OpenHarmony SDK

确保 Node.js 已安装（建议版本 16 或以上）

📋 安装前准备

在开始之前，请确保：

✅ 已完成所有前置软件的安装
✅ 已注册并实名认证华为开发者账号（用于签名和模拟器）
✅ 网络连接正常（需要下载大量依赖包）
✅ 至少 5 GB 可用磁盘空间
✅ 管理员权限（配置环境变量需要）

💡 小提示：整个搭建过程需要下载约 2-3 GB 的文件，建议在网络较好的环境下进行。

⚙️ 第一步：配置开发环境

在开始创建项目之前，我们需要配置一些环境变量和工具，这些配置是 React Native for OpenHarmony 开发所必需的。

📌 步骤 1：配置 hdc 环境变量

hdc（HarmonyOS Device Connector）是 OpenHarmony 提供的命令行调试工具，用于连接真机进行调试。

找到 hdc 工具路径

hdc 工具位于 OpenHarmony SDK 的 toolchains 目录下，路径格式为：

复制代码

{DevEco Studio安装路径}/sdk/{SDK版本}/openharmony/toolchains

如何找到这个路径？

打开 DevEco Studio
"File" → "Settings" → "OpenHarmony SDK"
查看 SDK Location，然后找到 openharmony/toolchains 目录

示例路径：

C:\Users\你的用户名\AppData\Local\Huawei\Sdk\default\openharmony\toolchains
D:\Tools\Huawei\Sdk\default\openharmony\toolchains

添加到 PATH 环境变量

🖱️ 右键点击 "开始" 按钮（或按 Win + X）
👆 点击 "系统" → "高级系统设置" → "环境变量"
🔍 在 "系统变量" 区域，找到 "Path" 变量
✏️ 点击 "编辑"，添加 hdc 工具的完整路径

💡 小提示 ：确保路径正确，指向 toolchains 目录，这样系统才能找到 hdc.exe 命令。

📌 步骤 2：配置 HDC_SERVER_PORT 环境变量

hdc 需要一个端口来连接设备，我们需要配置端口号。

➕ 在 "系统变量" 区域，点击 "新建" 按钮
📝 填写变量信息：
- 变量名 ：HDC_SERVER_PORT
- 变量值 ：7035（或任意未被占用的端口号）
✅ 点击 "确定" 保存

💡 小提示 ：端口号可以是任意未被占用的端口，7035 是常用的默认值。

📌 步骤 3：配置 CAPI 版本环境变量

当前 React Native for OpenHarmony 框架默认使用 CAPI（Component API）架构，需要配置环境变量来启用。

➕ 在 "系统变量" 区域，点击 "新建" 按钮
📝 填写变量信息：
- 变量名 ：RNOH_C_API_ARCH
- 变量值 ：1
✅ 点击 "确定" 保存

💡 小提示 ：1 表示启用 CAPI 架构，这是当前推荐的架构方式。

📌 步骤 4：配置 npm 镜像源（可选但推荐）

为了加快 npm 包的下载速度，建议配置国内镜像源。

创建 .npmrc 文件

📁 打开文件资源管理器，导航到 C:\Users\你的用户名\
📝 如果没有 .npmrc 文件，创建一个新文件（注意文件名以点开头）
✏️ 编辑文件，添加以下内容：

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

⚠️ 安全提示 ：关闭 SSL 证书校验可以加快下载速度，但会降低安全性。如果对安全性要求较高，可以只配置 registry，不关闭 SSL 校验。

清理 npm 缓存

配置完成后，在命令提示符中执行：

bash 复制代码

npm cache clean --force

⚠️ 重要提示 ：修改 registry 后必须执行 npm cache clean --force 清理缓存，否则新的镜像源不会生效。

📌 步骤 5：验证环境配置

配置完成后，验证环境变量是否生效：

🔄 关闭所有已打开的命令提示符窗口
🆕 重新打开命令提示符
✅ 验证 hdc 命令：

bash 复制代码

hdc version

如果显示版本信息，说明 hdc 配置成功！

⚠️ 必须重新打开命令提示符：配置环境变量后，必须关闭所有已打开的命令提示符窗口，然后重新打开，环境变量才会生效！

📦 React Native 鸿蒙化版本信息

当前 React Native 鸿蒙版本基于社区 RN 0.72.5 进行适配，以下是版本信息：

核心包版本

名称	版本号
react-native-harmony.tgz	0.72.90
react-native-harmony-cli.tgz	0.0.37
react_native_openharmony-6.0.0.508.har	0.72.90
react_native_openharmony_release-6.0.0.508.har	6.0.0.508

配套工具版本

名称	版本号
DevEco Studio	Deveco Studio 6.0.0.847SP1（配套SDK6.0.0.47(SP10)）
HarmonyOS SDK	HarmonyOS SDK 6.0.0.47(SP15)
手机ROM	ALN-AL00 206.0.0.47(SP15DEVC00E47R4P6) ALN-AL80 206.0.0.47(SP15DEVC00E47R4P6) BRA-AL00 206.0.0.47(SP15DEVC00E47R4P4)

💡 重要提示：

该版本依赖的 OpenHarmony SDK 最低版本为 API 20

目前 React Native for OpenHarmony 仅支持 0.72.5 版本的 React Native

其他版本信息可查看 React Native For OpenHarmony 版本说明

⚠️ 约束条件

如果你需要自定义 CMakeLists.txt，请将 so 库命名为 rnoh_app：

cmake 复制代码

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

💡 小提示 ：库名称必须为 rnoh_app，否则可能导致编译或运行错误。

🆕 第二步：创建 React Native 工程

现在开始创建第一个 React Native 项目。我们将使用 React Native 内置的命令行工具，它不需要单独安装，可以直接使用 Node.js 自带的 npx 命令。

📌 步骤 1：选择项目存储位置

📂 选择一个合适的目录来存放项目（例如：D:\Projects 或 C:\Development）
🖱️ 在该目录右键，点击 "在终端中打开" 或 "Open in Terminal"
📋 命令提示符会自动定位到当前目录

💡 小提示：

建议选择一个空间充足的磁盘位置

路径中不要包含中文字符，避免潜在问题

确保有足够的磁盘空间（至少 500 MB）

📌 步骤 2：创建 React Native 工程

执行以下命令创建新工程（以 AtomGitNews 为例，你可以替换为你自己的项目名称）：

shell 复制代码

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

⚠️ 重要提示 ：必须使用 0.72.5 版本，这是目前 React Native for OpenHarmony 唯一支持的版本。

📌 步骤 3：确认安装

首次创建 React Native 工程时，会提示需要安装 react-native@0.72.5：

📋 查看提示信息
✅ 按回车键确认安装

💡 小提示：这个过程可能需要几分钟，取决于网络速度。

📌 步骤 4：等待工程创建完成

等待工程创建完成，你会看到类似以下的输出：

🎉 恭喜！ React Native 工程创建成功！
💡 小提示：

工程创建完成后，会自动安装依赖包

如果依赖安装失败，可以进入项目目录后手动执行 npm install

创建的项目已经包含了基本的 React Native 代码结构

📱 第三步：创建鸿蒙工程

React Native 工程创建完成后，我们需要创建一个对应的鸿蒙应用工程。这个工程将作为 React Native 代码在 HarmonyOS 平台上的载体。

📌 步骤 1：打开 DevEco Studio

🚀 启动 DevEco Studio
👆 在欢迎界面，点击 "Create Project" 按钮，打开工程创建向导

📌 步骤 2：选择工程模板

📋 在工程创建向导界面，选择 "Empty Ability" 模板
👆 点击 "Next" 按钮继续

💡 小提示：Empty Ability 是一个空的应用模板，适合集成 React Native。

📌 步骤 3：配置工程信息

📝 填写工程配置信息：
- 工程名称：可以保持默认或自定义
- 工程包名 ：保持默认即可（例如：com.example.myapplication）
- 工程存储位置 ：重要 - 选择 React Native 工程根目录，并设置子目录名称为 harmony
- 最低兼容SDK版本：选择 API 20 或更高版本
- 模块名称：保持默认即可
- 设备类型 ：选择 Phone（手机）
⚠️ 重要：工程存储位置必须设置为：
复制代码
```
{React Native工程根目录}/harmony
```
例如：D:\Projects\AtomGitNews\harmony

⚠️ 重要提示：

鸿蒙工程必须创建在 React Native 工程根目录下

目录名称必须为 harmony（小写）

这样可以减少 bundle 文件的拷贝流程，简化开发

📌 步骤 4：完成工程创建

✅ 检查配置信息无误后，点击 "Finish" 按钮
⏳ 等待工程创建完成

🎉 恭喜！ 鸿蒙工程创建成功！
💡 小提示：工程创建完成后，DevEco Studio 会自动打开项目，等待索引完成即可开始开发。

📦 第四步：安装鸿蒙依赖包并生成 bundle

现在我们需要为 React Native 工程安装 OpenHarmony 适配包，并配置 Metro 打包工具来生成 bundle 文件。

📌 步骤 1：添加 harmony 脚本

使用 VS Code 或其他工具打开创建的 AtomGitNews 工程，打开根目录下的 package.json 配置文件，在配置文件 scripts 属性中新增 OpenHarmony 依赖"harmony": "react-native bundle-harmony --dev"。

json 复制代码

{
  "name": "AtomGitNews",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "lint": "eslint .",
    "start": "react-native start",
    "test": "jest",
    "harmony": "react-native bundle-harmony --dev"
  },
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.72.5"
  },
  "devDependencies": {
    "@babel/core": "^7.20.0",
    "@babel/preset-env": "^7.20.0",
    "@babel/runtime": "^7.20.0",
    "@react-native/eslint-config": "^0.72.2",
    "@react-native/metro-config": "^0.72.11",
    "@tsconfig/react-native": "^3.0.0",
    "@types/react": "^18.0.24",
    "@types/react-test-renderer": "^18.0.0",
    "babel-jest": "^29.2.1",
    "eslint": "^8.19.0",
    "jest": "^29.2.1",
    "metro-react-native-babel-preset": "0.76.8",
    "prettier": "^2.4.1",
    "react-test-renderer": "18.2.0",
    "typescript": "4.8.4"
  },
  "engines": {
    "node": ">=16"
  }
}

📌 步骤 2：安装鸿蒙化依赖包

📂 在 AtomGitNews 根目录下打开命令提示符工具
📥 执行以下命令安装依赖包（版本必须为 0.72.90）：

bash 复制代码

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

⚠️ 重要提示 ：依赖包版本必须为 0.72.90，与 React Native 鸿蒙化版本信息保持一致。

⏳ 等待安装完成（可能需要几分钟）

💡 小提示：

如果安装失败，检查网络连接或尝试使用代理

确保已配置 npm 镜像源（参考第一步）

如果遇到权限问题，尝试以管理员身份运行命令提示符

📌 步骤 3：配置 Metro 打包工具

在执行生成 bundle 命令前，需要先为 React Native 工程配置 OpenHarmony 能力。打开工程根目录下的 metro.config.js 文件，增加 OpenHarmony 适配代码。

js 复制代码

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
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);

📌 步骤 4：生成 bundle 文件

📂 在工程 AtomGitNews 根目录下打开命令提示符窗口
🚀 输入以下命令生成 bundle 文件：

bash 复制代码

npm run harmony

⏳ 等待 bundle 生成完成

✅ 生成的文件位置：
- AtomGitNews/harmony/entry/src/main/resources/rawfile/bundle.harmony.js - JavaScript bundle 文件
- AtomGitNews/harmony/entry/src/main/resources/rawfile/assets/ - 图片资源文件夹

💡 小提示：

bundle 文件包含了你的 React Native 代码和依赖

每次修改代码后，需要重新运行 npm run harmony 生成新的 bundle

开发模式下使用 --dev 参数，生产环境使用 --release 参数

如果生成失败，检查 metro.config.js 配置是否正确

🔧 第五步：在原生工程鸿蒙侧配置 React Native for OpenHarmony

现在我们需要在鸿蒙原生工程中集成 React Native for OpenHarmony，这样才能让 React Native 代码在 HarmonyOS 平台上运行。

📌 步骤 1：添加 React Native 配置

📂 在 AtomGitNews/harmony/entry 目录下打开命令提示符窗口

或者：
🖱️ 在 DevEco Studio 中，右键点击 entry 目录，选择 "Open In > Terminal" 在底部控制台打开命令提示符

📥 输入以下命令安装依赖包：

bash 复制代码

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

⚠️ 重要提示 ：版本必须为 0.72.90，与 React Native 引入的 @react-native-oh/react-native-harmony 依赖版本保持一致。

⏳ 执行完成后，会在工程级目录以及模块级目录下生成 oh_modules 文件夹

💡 小提示 ：ohpm 是 OpenHarmony 的包管理器，类似于 npm。

📌 步骤 2：集成 RNOH

现在需要补充 CPP 侧和 ArkTS 侧的代码来完成集成。

补充 CPP 侧代码

右键AtomGitNews/harmony/entry/src/main目录选择"New > Directory"创建cpp文件夹。

在cpp 目录右键选择"New > File "创建 CMakeLists.txt文件，并将 RNOH 的适配层代码添加到编译构建中生成 librnoh_app.so：

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

target_link_libraries(rnoh_app PUBLIC rnoh)

CMakeLists.txt代码编写完成后，点击右上角的Sync Now进行同步。

继续在cpp 目录右键选择"New > File "或者"New > C/C++ Source File"创建PackageProvider.cpp，需要导入RNOH/PackageProvider头文件并实现getPackages方法，getPackages方法用于创建三方库或自定义TurboModule或Fabric的package对象。

注：当前不涉及三方库与自定义TurboModule或组件，需要返回空对象。

cpp 复制代码

#include "RNOH/PackageProvider.h"

using namespace rnoh;

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

PackageProvider.cpp代码编写完成后，点击右上角的Sync Now进行同步。

同步完成后，会发现PackageProvider.cpp中代码有红色标记，可以先不处理。打开 AtomGitNews\entry\build-profile.json5，将cpp中的代码添加到应用工程的编译构建任务中；如果在 x86_64 架构的模拟器上运行应用，需在 externalNativeOptions 配置中额外添加 abiFilters 字段，并包含 x86_64 架构参数，如下所示，abiFilters 字段当前被注释，默认仅构建适用于 arm64-v8a 架构的版本。最后点击编辑器右上角Sync Now同步工程。

json 复制代码

{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": "",
      "abiFilters": ["arm64-v8a", "x86_64"]
    },
    "resOptions": {
      "copyCodeResource": {
        "enable": false
      }
    }
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      }
    },
  ],
  "targets": [
    {
      "name": "default"
    },
    {
      "name": "ohosTest",
    }
  ]
}

最后，打开CMakeLists.txt文件，会发现自动加入的PackageProvider.cpp路径有误，需要调整成正确的，调整完成后点击编辑器右上角Sync Now同步工程，这时PackageProvider.cpp中的红色信息将消失。

cmake 复制代码

// 原代码
// add_library(rnoh_app SHARED
//    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp" PackageProvider.cpp)

// 调整为
add_library(rnoh_app SHARED
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp" "./PackageProvider.cpp")

补充ArkTS侧的代码

CPP侧代码完成后，需要继续补全ArkTS侧代码。在AtomGitNews/entry/src/main/ets/entryability/EntryAbility.ets中原有的UIAbility替换为react-native-openharmony依赖包提供的RNAbility，并重写getPagePath返回，使其返回程序的入口page。

typescript 复制代码

// 原写法
// import { UIAbility } from '@kit.AbilityKit';
// export default class EntryAbility extends UIAbility {...}

// 修改为
import { RNAbility } from '@rnoh/react-native-openharmony';
export default class EntryAbility extends RNAbility {...}

修改后，会提示错误信息，将鼠标放置在EntryAbility类名上，会显示具体的错误信息。

提示信息告诉我们少了getPagePath方法，可以手动添加该方法，也可以直接点击错误提示框中的Implement inherited abstract class自动添加getPagePath方法，当然还需要我们手动增加返回程序入口page的代码。

typescript 复制代码

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

接着将鼠标放置在onCreate方法上，提示我们RNAbility提供的onCreate方法只需要一个参数，而目前是两个参数，需要手动修改并增加调用super方法来确保原有功能不丢失。

注意事项：

需确保函数的参数列表与父类保持兼容。

建议添加override关键字，以提升代码可读性并增强编译器检查。

typescript 复制代码

// 原有代码
// onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {}

// 修改后的代码
override onCreate(want: Want): void {
    super.onCreate(want);
    ...
}

接下来我们需要在AtomGitNews/entry/src/main/ets目录右键选择"New > ArkTS File"创建RNPackagesFactory.ets文件，该文件需要导入@rnoh/react-native-openharmony的RNPackageContext和RNPackage，并导出用于创建TurboModule、Fabric的package对象的createRNPackages方法。

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

typescript 复制代码

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

最后，打开AtomGitNews/entry/src/main/ets/pages/Index.ets添加RNOH的使用代码。

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

typescript 复制代码

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")
    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()
    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
            arkTsComponentNames: []
          },
          initialProps: { "foo": "bar" } as Record<string, string>,
          appKey: "AtomGitNews",
          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%')
  }
}

📱 第六步：在模拟器运行 RNOH 跨平台应用

配置完成后，我们可以在模拟器上运行应用进行验证。

📌 步骤 1：打开设备管理

🔍 在 DevEco Studio 工具栏，点击 "No Devices" 下拉菜单
👆 选择 "Device Manager" 打开设备管理窗口

📌 步骤 2：创建模拟器

➕ 在设备管理窗口中点击 "New Emulator" 按钮，打开新建模拟器窗口

📥 下载 Version(API) 对应版本为 HarmonyOS 6.0.0(20) 的 Huawei_Phone 模拟器镜像
⏳ 下载完成后点击 "Next" 按钮创建模拟器

⏱️ 下载时间：镜像文件较大（约 1-2 GB），下载可能需要 10-30 分钟。

⚙️ 保持默认模拟器参数即可，点击 "Finish" 按钮完成创建

📌 步骤 3：启动模拟器

📱 创建成功后，会在设备管理列表中显示当前创建的模拟器
▶️ 点击 "Actions" 列的运行按钮，启动模拟器

⏳ 等待模拟器启动完成（首次启动可能需要 1-2 分钟）
✅ 模拟器启动成功后，工具栏 "No Devices" 会显示当前已连接的设备名称

📌 步骤 4：运行应用

▶️ 点击工具栏的运行或调试按钮（绿色三角形图标）
📱 应用程序会自动安装到已选择的设备上（此处为模拟器）

⏳ 等待工程编译构建安装完成（首次运行可能需要几分钟）
🎉 模拟器显示应用界面，即为成功！

💡 小提示：

如果运行失败，检查错误信息

确保 bundle 文件已正确生成

确保 appKey 配置正确

查看 DevEco Studio 的日志输出

至此，已初步完成原生工程鸿蒙侧React Native for OpenHarmony的所有配置并能够正常在模拟器运行。

🎉 总结

恭喜你完成了 React Native for OpenHarmony 开发环境的搭建！现在你已经可以：

✅ 使用 React Native 开发 HarmonyOS 应用
✅ 在模拟器或真机上运行和调试应用
✅ 生成和部署 HAP 安装包
✅ 开始你的跨平台应用开发之旅

❓ 常见问题（FAQ）

Q1: 环境变量配置后不生效怎么办？

必须重新打开命令提示符：配置环境变量后，已打开的命令提示符不会自动更新
关闭所有命令提示符窗口
重新打开命令提示符
如果还不行，尝试重启电脑

Q2: `npm i` 安装依赖失败怎么办？

A: 可能的原因：

网络连接问题
npm 镜像源未配置
权限问题

解决方法：

检查网络连接
配置 npm 镜像源（参考第一步）
执行 npm cache clean --force 清理缓存
尝试使用代理或 VPN
以管理员身份运行命令提示符

Q3: `npm run harmony` 生成 bundle 失败？

A: 可能的原因：

Metro 配置不正确
依赖包未正确安装
路径问题

解决方法：

检查 metro.config.js 配置是否正确
确保已安装 @react-native-oh/react-native-harmony 包
检查项目路径中是否包含中文字符
查看错误信息，根据具体错误进行排查

Q4: 应用运行时出现白屏？

A: 可能的原因：

appKey 与 AppRegistry.registerComponent 注册的名称不一致
bundle 文件未正确生成或路径错误
代码错误导致崩溃

解决方法：

检查 Index.ets 中的 appKey 是否与 React Native 代码中的注册名称一致
确保 bundle 文件已正确生成并放在正确位置
查看 DevEco Studio 的日志输出，查找错误信息
检查 React Native 代码是否有语法错误

Q5: 模拟器无法启动？

A: 可能的原因：

虚拟化功能未启用（BIOS 中启用 VT-x 或 AMD-V）
磁盘空间不足
模拟器镜像损坏

解决方法：

检查 BIOS 中是否启用了虚拟化功能
确保有足够的磁盘空间（至少 5 GB）
尝试删除并重新创建模拟器
检查模拟器日志，查看具体错误信息

Q6: 编译构建失败？

A: 可能的原因：

CMakeLists.txt 配置错误
PackageProvider.cpp 路径错误
build-profile.json5 配置错误

解决方法：

检查 CMakeLists.txt 中的路径是否正确
确保 PackageProvider.cpp 路径使用 "./PackageProvider.cpp"
检查 build-profile.json5 中的 externalNativeOptions 配置
点击 DevEco Studio 右上角的 Sync Now 同步工程
查看编译错误信息，根据提示修复

Q7: hdc 命令找不到？

A: 可能的原因：

hdc 路径未添加到 PATH 环境变量
路径配置错误
SDK 未正确安装

解决方法：

检查 PATH 环境变量中是否添加了 hdc 工具路径
确保路径指向 toolchains 目录
检查 DevEco Studio SDK 是否正确安装
重新打开命令提示符

Q8: 如何更新 React Native for OpenHarmony 版本？

查看 React Native For OpenHarmony 版本说明
更新 package.json 中的依赖版本
执行 npm install 更新依赖
更新 ohpm 包版本
重新生成 bundle 文件

Q9: 真机调试连接失败？

A: 可能的原因：

hdc 环境变量未配置
设备未启用 USB 调试
驱动问题

解决方法：

确保 hdc 环境变量已正确配置
在设备上启用 USB 调试模式
检查 USB 驱动是否正确安装
使用 hdc list targets 查看连接的设备

Q10: 如何查看详细的错误日志？

在 DevEco Studio 底部查看 "Log" 窗口
在模拟器或真机上查看应用日志
使用 hdc hilog 命令查看系统日志
检查 React Native Metro 打包器的输出
ckageProvider.cpp路径使用"./PackageProvider.cpp"`

检查 build-profile.json5 中的 externalNativeOptions 配置
点击 DevEco Studio 右上角的 Sync Now 同步工程
查看编译错误信息，根据提示修复

Q7: hdc 命令找不到？

A: 可能的原因：

hdc 路径未添加到 PATH 环境变量
路径配置错误
SDK 未正确安装

解决方法：

检查 PATH 环境变量中是否添加了 hdc 工具路径
确保路径指向 toolchains 目录
检查 DevEco Studio SDK 是否正确安装
重新打开命令提示符

Q8: 如何更新 React Native for OpenHarmony 版本？

查看 React Native For OpenHarmony 版本说明
更新 package.json 中的依赖版本
执行 npm install 更新依赖
更新 ohpm 包版本
重新生成 bundle 文件

Q9: 真机调试连接失败？

A: 可能的原因：

hdc 环境变量未配置
设备未启用 USB 调试
驱动问题

解决方法：

确保 hdc 环境变量已正确配置
在设备上启用 USB 调试模式
检查 USB 驱动是否正确安装
使用 hdc list targets 查看连接的设备

Q10: 如何查看详细的错误日志？

在 DevEco Studio 底部查看 "Log" 窗口
在模拟器或真机上查看应用日志
使用 hdc hilog 命令查看系统日志
检查 React Native Metro 打包器的输出

Windows 11 OpenHarmony版React Native开发环境搭建完整指南

📖 什么是 React Native for OpenHarmony？

🖥️ 测试环境

📋 前置条件

📋 安装前准备

⚙️ 第一步：配置开发环境

📌 步骤 1：配置 hdc 环境变量

找到 hdc 工具路径

添加到 PATH 环境变量

📌 步骤 2：配置 HDC_SERVER_PORT 环境变量

📌 步骤 3：配置 CAPI 版本环境变量

📌 步骤 4：配置 npm 镜像源（可选但推荐）

创建 .npmrc 文件

清理 npm 缓存

📌 步骤 5：验证环境配置

📦 React Native 鸿蒙化版本信息

核心包版本

配套工具版本

⚠️ 约束条件

🆕 第二步：创建 React Native 工程

📌 步骤 1：选择项目存储位置

📌 步骤 2：创建 React Native 工程

📌 步骤 3：确认安装

📌 步骤 4：等待工程创建完成

📱 第三步：创建鸿蒙工程

📌 步骤 1：打开 DevEco Studio

📌 步骤 2：选择工程模板

📌 步骤 3：配置工程信息

📌 步骤 4：完成工程创建

📦 第四步：安装鸿蒙依赖包并生成 bundle

📌 步骤 1：添加 harmony 脚本

📌 步骤 2：安装鸿蒙化依赖包

📌 步骤 3：配置 Metro 打包工具

📌 步骤 4：生成 bundle 文件

🔧 第五步：在原生工程鸿蒙侧配置 React Native for OpenHarmony

📌 步骤 1：添加 React Native 配置

📌 步骤 2：集成 RNOH

补充 CPP 侧代码

补充ArkTS侧的代码

📱 第六步：在模拟器运行 RNOH 跨平台应用

📌 步骤 1：打开设备管理

📌 步骤 2：创建模拟器

📌 步骤 3：启动模拟器

📌 步骤 4：运行应用

🎉 总结

❓ 常见问题（FAQ）

Q1: 环境变量配置后不生效怎么办？

Q2: npm i 安装依赖失败怎么办？

Q3: npm run harmony 生成 bundle 失败？

Q4: 应用运行时出现白屏？

Q5: 模拟器无法启动？

Q6: 编译构建失败？

Q7: hdc 命令找不到？

Q8: 如何更新 React Native for OpenHarmony 版本？

Q9: 真机调试连接失败？

Q10: 如何查看详细的错误日志？

Q7: hdc 命令找不到？

Q8: 如何更新 React Native for OpenHarmony 版本？

Q9: 真机调试连接失败？

Q10: 如何查看详细的错误日志？

Q2: `npm i` 安装依赖失败怎么办？

Q3: `npm run harmony` 生成 bundle 失败？