React Native for OpenHarmony 0.84.3 环境搭建到项目运行从 0 到 1 全流程适用版本React Native 0.84.1RNOH 0.84.3写作日期2026-09-04平台macOSWindows / Linux 差异会在文中标注环境快照Node v26.0.0 / pnpm 11.8.0 / DevEco Studio 26.0.0 / HarmonyOS SDK API 26目录背景什么是 RNOH环境要求与版本矩阵环境检查确认当前机器是否达标安装与配置DevEco Studio、SDK、hdc、环境变量创建 React Native 工程接入鸿蒙化依赖react-native-oh/react-native-harmony生成鸿蒙壳工程init-harmony生成 bundle 并验证在 DevEco Studio 中运行到真机常见问题排查总结1. 背景什么是 RNOHRNOHReact Native for OpenHarmony / HarmonyOS是华为与社区共同推动的 React Native 鸿蒙化适配方案核心包为react-native-oh/react-native-harmony它让使用 React Native 编写的业务代码可以直接运行在鸿蒙HarmonyOS / OpenHarmony设备上。RNOH 的发展主线以0.XX版本号对齐社区 React NativeRNOH 版本状态说明0.72legacy早期稳定版API Level ≥ 90.77stableReact 18 兼容使用广泛0.82stableCAPI 架构成为默认Node ≥ 22.110.84main / 最新特性线本文目标版本CAPI 默认架构⚠️版本对应关系RNOH 0.84.3 的 peer 依赖要求react-native 0.84.1不是 0.84.3初始化工程时--version要传 0.84.1鸿蒙化依赖则用 0.84.3。2. 环境要求与版本矩阵RNOH 0.82含 0.84的硬性要求如下这也是环境检测脚本check-env.mjs的判定标准工具0.84 要求说明Node.js≥ 22.11只要求最低版本高版本均可如 26.xpnpm≥ 10可选推荐DevEco Studio26.x或 6.1.0RNOH 0.86 起要求 API 17 及以上HarmonyOS SDKAPI ≥ 17DevEco Studio 6.1默认带hdc在 PATH 中位于 SDKtoolchains目录RNOH_C_API_ARCH 1必需CAPI 是 0.82 默认架构未设置会导致运行时崩溃HDC_SERVER_PORT任意未占用端口推荐 7035DEVECO_SDK_HOMECLI 命令依赖macOS 设为.../Contents/sdk⚠️ 三个容易踩的坑只装 IDE 不装 SDK——OpenHarmony SDK 必须在 DevEco Studio 内单独下载RNOH_C_API_ARCH忘记设置——0.82 必需否则运行时回退旧架构崩溃macOS 下环境变量写入错误的 shell 配置——先echo $SHELL确认zsh →~/.zshrcbash →~/.bash_profile。3. 环境检查确认当前机器是否达标搭建前先全面检查本机现状避免装到一半才发现缺东西。可以按下面的命令逐项核对这里给出本次搭建时的真实输出# 1. Shell 类型决定环境变量写入哪个配置文件echo$SHELL# /bin/zsh → 写入 ~/.zshrc# 2. 核心工具链版本node--version# v26.0.0 ✅ ≥ 22.11npm--version# 11.12.1pnpm--version# 11.8.0 ✅ ≥ 10git--version# git version 2.39.5# 3. DevEco Studio 与 SDK# macOS 上查看安装版本cat/Applications/DevEco-Studio.app/Contents/Resources/version.txt# 26.0.0 ✅# 查看 SDK 的 API Levelsdk-pkg.json 中 apiVersion 字段cat/Applications/DevEco-Studio.app/Contents/sdk/default/sdk-pkg.json# 输出示例: apiVersion: 26, platformVersion: 26.0.0 # ✅ API 26 ≥ 17# 4. hdc 是否在 PATHwhichhdc# /Users/nutpi/Library/OpenHarmony/Sdk/26.0.0/toolchains/hdchdc--version# Ver: 3.2.0e# 5. 环境变量echo$RNOH_C_API_ARCH# 1 ✅ 必需echo$HDC_SERVER_PORT# 7035 ✅ 推荐echo$DEVECO_SDK_HOME# /Applications/DevEco-Studio.app/Contents/sdk# 6. npm 镜像源中国大陆网络建议华为云镜像npmconfig get registry# https://registry.npmjs.org/官方源可达可不换3.1 环境检查结果速览检查项要求本机结果状态Node.js≥ 22.11v26.0.0✅pnpm≥ 1011.8.0✅git有2.39.5✅DevEco Studio26.x / 6.1.026.0.0✅HarmonyOS SDKAPI ≥ 17API 26 (26.0.0.23)✅hdcPATH 中3.2.0e✅RNOH_C_API_ARCH11✅HDC_SERVER_PORT任意7035✅DEVECO_SDK_HOMECLI 依赖已设置✅npm registry建议镜像官方源连通正常✅本次搭建的机器环境全部达标无需额外安装如果你的机器有缺失项继续看下一节按需安装。4. 安装与配置DevEco Studio、SDK、hdc、环境变量如果你的检查结果全是 ✅可直接跳到第 5 节。4.1 安装 DevEco Studio含 OpenHarmony SDK从开发工具官网下载安装 DevEco StudiomacOS 默认安装到/Applications/DevEco-Studio.app。打开 DevEco Studio →Preferences → SDKWindows 为File → Settings → SDK勾选OpenHarmony SDK确认 API Level 满足版本矩阵要求0.84 需 API ≥ 17。点击Apply等待 SDK 下载完成。⛔ 千万别跳过 SDK 安装——仅装 IDE 是不够的hdc、编译工具链都在 SDK 里。4.2 配置 hdc 到 PATHhdcOpenHarmony Device Connector是鸿蒙命令行调试工具位于 SDK 的toolchains目录。macOS 下编辑~/.zshrc# 将 toolchains 目录加入 PATH按实际 SDK 路径填写exportPATH/Applications/DevEco-Studio.app/Contents/sdk/{SDK版本}/openharmony/toolchains:$PATH# 或如果你用的是独立 SDK如 ~/Library/OpenHarmony/Sdk/26.0.0/toolchainsexportPATH/Users/nutpi/Library/OpenHarmony/Sdk/26.0.0/toolchains:$PATH# HDC 端口任意未占用端口HDC_SERVER_PORT7035launchctl setenv HDC_SERVER_PORT$HDC_SERVER_PORTexportHDC_SERVER_PORT生效后验证source ~/.zshrc hdc --version。⚠️ Windows 用户在「系统环境变量」GUI 中配置后需要完全重启 VS Code / 终端才能生效VS Code 启动时会缓存环境变量。4.3 配置 RNOH_C_API_ARCH0.82 必需CAPI 架构是 RNOH 0.82 的默认架构未设置该变量会导致运行时回退旧架构引发崩溃。macOS 写入~/.zshrcexportRNOH_C_API_ARCH1验证echo $RNOH_C_API_ARCH应输出1。4.4 配置 DEVECO_SDK_HOMECLI 命令依赖react-native run-harmony、bundle-harmony等 CLI 命令依赖该变量。macOS 默认安装路径下只需设为 SDK 基址exportDEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdkmacOS 注意默认安装路径下无需设置DEVECO_HOME工具链会自动识别仅非默认路径才需要。4.5 可选配置 npm 华为云镜像中国大陆网络环境下npm install走官方源容易超时可在~/.npmrc配置华为云镜像registryhttps://repo.huaweicloud.com/repository/npm/⚠️ 不要全局关闭strict-ssl/sslVerify有中间人攻击风险仅在个别包 SSL 报错时对镜像域名单独关闭。修改后执行npm cache clean --force清缓存。5. 创建 React Native 工程使用社区 CLI 初始化工程版本必须传 0.84.1RNOH 0.84.3 对应的 react-native 版本npx react-native init已废弃# 在目标目录下执行--skip-install 可跳过 iOS 依赖下载mac 下耗时较长鸿蒙开发用不到npx react-native-community/clilatest init AwesomeProject--version0.84.1 --skip-install创建完成后工程结构大致如下AwesomeProject/ ├── App.tsx # RN 入口组件 ├── index.js # AppRegistry.registerComponent(AwesomeProject, ...) ├── app.json # { name: AwesomeProject } ├── metro.config.js # Metro 打包配置后续要改 ├── package.json # 依赖清单后续要改 ├── android/ ios/ ... # 安卓 / iOS 平台工程 此时还没有harmony/目录鸿蒙壳工程会在第 7 节生成。6. 接入鸿蒙化依赖6.1 安装 RNOH 依赖包在AwesomeProject目录下安装鸿蒙化依赖两个包版本都对齐 RNOH 0.84.3npminstallreact-native-oh/react-native-harmony0.84.3 react-native-oh/react-native-harmony-cli0.84.3验证安装node-econsole.log(require(./node_modules/react-native-oh/react-native-harmony/package.json).version)# 0.84.36.2 修改 package.json添加 bundle 命令在scripts下新增dev脚本用于生成鸿蒙 bundlescripts: { android: react-native run-android, ios: react-native run-ios, lint: eslint ., start: react-native start, - test: jest test: jest, dev: react-native bundle-harmony --dev },6.3 修改 metro.config.js添加鸿蒙适配const{mergeConfig,getDefaultConfig}require(react-native/metro-config);const{createHarmonyMetroConfig}require(react-native-oh/react-native-harmony/metro.config);/** * Metro configuration * https://reactnative.dev/docs/metro * * type {import(react-native/metro-config).MetroConfig} */constconfig{transformer:{getTransformOptions:async()({transform:{experimentalImportSupport:false,inlineRequires:true,},}),},};module.exportsmergeConfig(getDefaultConfig(__dirname),createHarmonyMetroConfig({reactNativeHarmonyPackageName:react-native-oh/react-native-harmony,}),config);6.4 替换 App.tsx避免鸿蒙白屏新生成的App.tsx依赖react-native-safe-area-context在鸿蒙上会导致白屏按官方文档替换为不带 safe-area 的版本import { NewAppScreen } from react-native/new-app-screen; import { StatusBar, StyleSheet, useColorScheme, View } from react-native; function App() { const isDarkMode useColorScheme() dark; return ( View style{styles.container} StatusBar barStyle{isDarkMode ? light-content : dark-content} / NewAppScreen templateFileNameApp.tsx safeAreaInsets{{ top: 0, bottom: 0, left: 0, right: 0 }} / /View ); } const styles StyleSheet.create({ container: { flex: 1, }, }); export default App;⚠️RNApp的appKey必须与index.js中AppRegistry.registerComponent注册的 appName来自app.json的 name一致否则白屏。7. 生成鸿蒙壳工程init-harmonyRNOH CLI 注册了react-native init-harmony命令可在 RN 工程内直接生成harmony/壳工程npx react-native init-harmony --bundle-name com.awesomeproject.app --app-name AwesomeProject--bundle-name必填三段式包名如com.org.project正则^[a-zA-Z][0-9a-zA-Z_.]$且含两个点--app-name应用名默认取 package.json 的 name。命令成功后success Created ./harmony directoryharmony/目录结构harmony/ ├── AppScope/ ├── build-profile.json5 ├── build-profile.template.json5 ├── codelinter.json ├── entry/ # 鸿蒙 entry 模块RNAbility、RNPackagesFactory、Index.ets… ├── hvigor/ │ └── hvigor-config.json5 # 引用 RNOH hvigor 插件rnoh-hvigor-plugin-0.84.3.tgz ├── hvigorfile.ts └── oh-package.json5 # 依赖 rnoh/react-native-openharmony指向本地 har7.1 遇到的坑Node 26 下 init-harmony 崩溃本次搭建在 Node v26.0.0 下运行init-harmony时报错TypeError [ERR_INVALID_ARG_TYPE]: The paths[0] argument must be of type string. Received undefined at new AbsolutePath (.../core/AbsolutePath.js:20:42) at get path (.../io/RealFS.js:40:16) at findRNOHHvigorPluginPath (.../commands/init-harmony.js:203:23)根因RNOH CLI 0.84.x 的RealFSDirent.pathgetter 依赖fs.Dirent.path属性而 Node 26 不再填充该属性path in dirent false。解决方案写一个 preload shim为readdirSync返回的 Dirent 对象补上path属性fs.Dirent.path语义就是「父目录路径」// shim-dirent-path.js — 临时补丁绕过 Node 26 与 RNOH CLI 的兼容问题constfsrequire(node:fs);constorigReaddirSyncfs.readdirSync;fs.readdirSyncfunction(p,options){constresultorigReaddirSync.apply(this,arguments);constoptstypeofoptionsobjectoptions!null?options:undefined;if(optsopts.withFileTypesArray.isArray(result)){constbasetypeofpstring?p:String(p);for(constdirentofresult){if(!(pathindirent)){Object.defineProperty(dirent,path,{value:base,configurable:true,enumerable:true,});}}}returnresult;};带 shim 重新执行即可NODE_OPTIONS-r ./shim-dirent-path.jsnpx react-native init-harmony\--bundle-name com.awesomeproject.app --app-name AwesomeProject8. 生成 bundle 并验证8.1 生成 bundle运行npm run dev即react-native bundle-harmony --dev把 RN 侧代码打包成鸿蒙可加载的 bundlenpmrun dev成功后输出info Created harmony/entry/src/main/resources/rawfile/bundle.harmony.js info Copied 7 assets生成的产物harmony/entry/src/main/resources/rawfile/ ├── bundle.harmony.js # 约 5.2 MB └── assets/ # bundle 中引用的本地图片等资源8.2 验证bundle 与类型检查# 确认 bundle 已生成ls-lhharmony/entry/src/main/resources/rawfile/# RN 侧 TS 类型检查可选npx tsc--noEmitℹ️ 如果tsc报了hvigorfile.ts找不到ohos/hvigor-ohos-plugin/rnoh/hvigor-plugin之类的错可以忽略——这两个模块是 hvigor 原生构建插件由 DevEco Studio 构建时从 ohpm/hvigor 环境解析不属于 RN 侧 TS 代码问题App.tsx等 RN 侧代码无错误即可。8.3 可选Metro 热加载模式如果希望开发时用 Metro 热加载改代码即时生效启动 Metro 服务即可npmstartRNOH 壳工程的jsBundleProvider默认优先尝试MetroJSBundleProvider见harmony/entry/src/main/ets/pages/Index.ets再回退到本地 bundle 文件。9. 在 DevEco Studio 中运行到真机用 DevEco Studio 打开AwesomeProject/harmony目录等待后台任务ohpm install / SyncData / 首次全量编译 C完成——首次全量编译耗时较长请耐心等待。点击右上角用户图标 →Sign in登录华为账号。连接真机USB 调试可通过hdc list targets确认设备已连接。File Project Structure Signing Configs勾选Automatically generate signature点击OK自动签名。选择entry运行配置右上角点击Debug ‘entry’或 Run按钮运行。运行成功后App 启动流程EntryAbility继承自RNAbility→ 加载Index.ets页面 →RNApp加载 bundle → 渲染 React Native 组件。10. 常见问题排查现象可能原因解决方案init找不到模板react-native版本与 CLI 模板不匹配RNOH 0.84.3 用--version 0.84.1初始化init-harmony报paths[0]TypeErrorNode 26 下fs.Dirent.path缺失使用文中的shim-dirent-path.js补丁Bundle name validation failedbundle-name 不是三段式传com.org.project形式含两个点运行白屏App.tsx依赖 safe-area-context /appKey与注册名不一致替换 App.tsx见 6.4核对app.jsonnameRNOH_C_API_ARCH未设置崩溃0.82 默认 CAPI 架构export RNOH_C_API_ARCH1并写入 shell 配置npm install超时中国大陆网络配置华为云镜像见 4.5编译报错缺模块ohpm install / SyncData 未完成等待 DevEco 后台任务全部结束再编译11. 总结从 0 到 1 跑通 RNOH 0.84.3 的核心链路环境检查Node/DevEco/SDK/hdc/环境变量 → 创建 RN 工程react-native 0.84.1 → 安装鸿蒙化依赖react-native-oh/react-native-harmony0.84.3 → 配置 metro.config.js package.json → init-harmony 生成鸿蒙壳工程 → npm run dev 生成 bundle → DevEco Studio 签名并运行到真机要点回顾版本对应关系是最大的坑RNOH 0.84.3 的 RN 基座是 0.84.1初始化与依赖安装的版本要分开看环境变量要提前配齐RNOH_C_API_ARCH1必需、HDC_SERVER_PORT、DEVECO_SDK_HOME、hdc 的 PATHNode 26 兼容问题用 preload shim 即可绕过不影响项目本身白屏问题绝大多数是 safe-area-context 依赖或appKey不一致导致。配置好一次环境后后续新项目只需init→ 装依赖 → 改 metro/package.json →init-harmony→npm run dev→ DevEco 运行五分钟即可跑通一个新 RNOH 工程。本文基于 React Native鸿蒙化仓库 官方文档与真实搭建过程整理版本信息以 版本说明 为准。欢迎大家关注React Native鸿蒙化仓库社区。
