一、背景知识速览1.1 什么是 RNOHReact Native for OpenHarmony (RNOH)是让 React Native 应用能直接运行在 HarmonyOS 设备上的核心库。它由华为与 Software Mansion 等合作伙伴共同开发基于 React Native 新架构Fabric构建确保性能与可靠性。目前已有YY、小红书Little Red Book、携程等知名应用采用此方案超过2700万台设备运行在 HarmonyOS NEXT 上。1.2 鸿蒙化 RN 的技术特点相较于 Android/iOS 平台将 RN 组件转化为原生 UI 控件鸿蒙上的转化路径更短——直接将 JS/React 组件代码转化为ArkUI 后台 C 信息而非转化为 ArkUI 控件从而提升渲染效率。二、环境安装前置准备2.1 软件版本要求核心避坑点软件推荐版本说明DevEco Studio4.1.3.400 / 3.1.0.501鸿蒙官方 IDE需支持 ArkUI 3.0 桥接 APINode.jsv16.18.0 LTS 或 v18.14.1与 RN 0.72.x 兼容性最佳JDKJDK 11DevEco Studio 3.0 强制要求React Native0.72.5或0.77.1RNOH 当前官方支持的版本HarmonyOS SDKAPI 20对应 NEXT Developer Preview1⚠️关键提醒RNOH 目前支持 RN 0.72.5 和 0.77.1 两个版本。0.72.5 版本的框架和三方库生态更为成熟推荐生产项目优先考虑。2.2 鸿蒙开发环境安装Step 1注册开发者账号并申请权限目前最新版 OpenHarmony SDK 及 RNOH 相关 npm 包尚未完全对外开放个人开发者需先申请白名单成为合作伙伴。登录 HarmonyOS 应用开发门户 注册账号进入 DevEco Studio 套件货架中心申请白名单Step 2下载并安装 DevEco Studio白名单通过后下载对应版本的 DevEco Studio 安装包并完成安装。启动后根据引导配置 SDK 使用路径。Step 3配置 hdc 环境变量hdc是 OpenHarmony 调试命令行工具位于 SDK 的toolchains目录下text# Windows 环境变量添加 {DevEco Studio安装路径}/sdk/{SDK版本}/openharmony/toolchains # macOS/Linux 配置.bash_profile 或 .zshrc export PATH$TOOL_HOME/sdk/default/openharmony/toolchains:$PATH # hdc 端口可选设为未被占用端口如 7035 export HDC_SERVER_PORT7035验证安装终端输入hdc --version三、React Native 工程创建与鸿蒙化配置3.1 创建 RN 项目使用指定版本创建新项目以 0.72.5 为例bashnpx react-native0.72.5 init MyRNProject --version 0.72.5 cd MyRNProject3.2 安装鸿蒙适配依赖bash# 安装 RNOH 核心库 npm i react-native-oh/react-native-harmony # 如遇 bundle-harmony 命令报错需额外安装 npm install memfs^4.17.23.3 配置 package.json在scripts中新增鸿蒙打包命令json{ scripts: { dev: react-native bundle-harmony --dev } }3.4 配置 Metro 打包工具修改metro.config.js添加鸿蒙适配配置javascriptconst {mergeConfig, getDefaultConfig} 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 );3.5 生成 JS Bundlebashnpm run dev成功后会生成harmony/entry/src/main/resources/rawfile/bundle.harmony.js和assets/文件夹。四、鸿蒙原生工程集成 RNOH4.1 在 DevEco Studio 中创建鸿蒙工程在 RN 项目根目录下新建harmony文件夹用 DevEco Studio 在此目录创建新工程Compile SDK 选择 API 20配置签名File Project Structure Signing Configs勾选 Support HarmonyOS 和 Automatically generate signature登录华为账号4.2 安装鸿蒙侧依赖在entry目录下执行bashohpm i rnoh/react-native-openharmony4.3 补充 C 层代码在entry/src/main/cpp/目录下创建CMakeLists.txt配置 RNOH 适配层编译cmakeproject(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_CPP_DIR ${OH_MODULE_DIR}/rnoh/react-native-openharmony/src/main/cpp) 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)同时创建PackageProvider.cppcpp#include RNOH/PackageProvider.h using namespace rnoh; std::vectorstd::shared_ptrPackage PackageProvider::getPackages(Package::Context ctx) { return {}; }4.4 配置 build-profile.json5在entry/build-profile.json5中添加 externalNativeOptionsjson{ buildOption: { externalNativeOptions: { path: ./src/main/cpp/CMakeLists.txt, arguments: , cppFlags: } } }4.5 补充 ArkTS 侧代码将EntryAbility.ets继承改为RNAbilitytypescriptimport { RNAbility } from rnoh/react-native-openharmony; export default class EntryAbility extends RNAbility { getPagePath() { return pages/Index; } }创建RNPackagesFactory.etstypescriptimport { RNPackageContext, RNPackage } from rnoh/react-native-openharmony/ts; export function createRNPackages(ctx: RNPackageContext): RNPackage[] { return []; }4.6 修改 Index.ets 主页面在pages/Index.ets中加载 RNOH 核心上下文并渲染 RNApp。五、关键环境变量汇总变量名值说明RNOH_C_API_ARCH1启用 CAPI 版本架构必须配置HDC_SERVER_PORT7035或其他空闲端口hdc 调试端口PATH含 SDK/toolchains 路径使 hdc 命令可用registry.npmrchttps://repo.huaweicloud.com/repository/npm/华为 npm 镜像加速六、常见问题与解决方案6.1 error: unknown command bundle-harmony解决方案手动在 package.json 中添加memfs: ^4.17.2依赖重新安装后重试。6.2 App 启动后没有加载 Bundle原因端口映射未成功。执行以下命令bashhdc rport tcp:8081 tcp:80816.3 第三方库未生效原因node_modules被覆盖导致 metro 配置失效。检查node_modules/react-native-harmony/metro.config.js中fs.lstatSync是否已改为fs.statSyncpnpm 用户需注意。6.4 三方库未适配鸿蒙怎么办纯 JS 库可直接使用原库含原生代码的库查阅 RNOH 三方库文档 寻找已适配版本或寻找替代库6.5 需要申请白名单吗是的。目前 RNOH 相关工具链和 SDK 尚未全面开放个人开发者需要通过 HarmonyOS 应用开发门户申请白名单成为合作伙伴才能获取完整开发套件。七、写在最后RNOH 项目仍在快速发展中华为已承诺持续迭代更新。对于计划将 React Native 应用迁移到鸿蒙生态的开发者当前最稳妥的路径是使用RN 0.72.5版本严格按上述步骤配置环境参考官方 Gitee 仓库ohos_react_native的最新文档复杂功能如高性能动画、硬件调用建议结合ArkTS 原生开发实现以获得最佳性能和兼容性。