React Native for OpenHarmony 0.84.3 环境搭建到项目运行（从 0 到 1 全流程）

适用版本：React Native 0.84.1（RNOH 0.84.3）
写作日期：2026-09-04
平台：macOS（Windows / Linux 差异会在文中标注）
环境快照：Node v26.0.0 / pnpm 11.8.0 / DevEco Studio 26.0.0 / HarmonyOS SDK API 26

---

目录

1. 背景：什么是 RNOH
2. 环境要求与版本矩阵
3. 环境检查：确认当前机器是否达标
4. 安装与配置：DevEco Studio、SDK、hdc、环境变量
5. 创建 React Native 工程
6. 接入鸿蒙化依赖（@react-native-oh/react-native-harmony）
7. 生成鸿蒙壳工程（init-harmony）
8. 生成 bundle 并验证
9. 在 DevEco Studio 中运行到真机
10. 常见问题排查
11. 总结

---

1. 背景：什么是 RNOH

RNOH（React Native for OpenHarmony / HarmonyOS） 是华为与社区共同推动的 React Native 鸿蒙化适配方案，核心包为 @react-native-oh/react-native-harmony，它让使用 React Native 编写的业务代码可以直接运行在鸿蒙（HarmonyOS / OpenHarmony）设备上。

RNOH 的发展主线（以 0.XX 版本号对齐社区 React Native）：

RNOH 版本	状态	说明
0.72	legacy	早期稳定版，API Level ≥ 9
0.77	stable	React 18 兼容，使用广泛
0.82	stable	CAPI 架构成为默认，Node ≥ 22.11
0.84	main / 最新特性线	本文目标版本，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.x）
pnpm	≥ 10	可选，推荐
DevEco Studio	26.x 或 6.1.0+	RNOH 0.86 起要求 API 17 及以上
HarmonyOS SDK	API ≥ 17	DevEco Studio 6.1默认带
hdc	在 PATH 中	位于 SDK toolchains 目录
RNOH_C_API_ARCH	= 1（必需）	CAPI 是 0.82+ 默认架构，未设置会导致运行时崩溃
HDC_SERVER_PORT	任意未占用端口	推荐 7035
DEVECO_SDK_HOME	CLI 命令依赖	macOS 设为 .../Contents/sdk

⚠️ 三个容易踩的坑：

1. 只装 IDE 不装 SDK——OpenHarmony SDK 必须在 DevEco Studio 内单独下载；
2. RNOH_C_API_ARCH 忘记设置——0.82+ 必需，否则运行时回退旧架构崩溃；
3. macOS 下环境变量写入错误的 shell 配置——先 echo $SHELL 确认（zsh → ~/.zshrc，bash → ~/.bash_profile）。

---

3. 环境检查：确认当前机器是否达标

搭建前先全面检查本机现状，避免装到一半才发现缺东西。可以按下面的命令逐项核对（这里给出本次搭建时的真实输出）：

# 1. Shell 类型（决定环境变量写入哪个配置文件）
echo $SHELL                      # /bin/zsh  → 写入 ~/.zshrc

# 2. 核心工具链版本
node --version                   # v26.0.0        ✅ ≥ 22.11
npm --version                    # 11.12.1
pnpm --version                   # 11.8.0         ✅ ≥ 10
git --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 Level（sdk-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 是否在 PATH
which hdc                        # /Users/nutpi/Library/OpenHarmony/Sdk/26.0.0/toolchains/hdc
hdc --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 镜像源（中国大陆网络建议华为云镜像）
npm config get registry          # https://registry.npmjs.org/（官方源可达可不换）

3.1 环境检查结果速览

检查项	要求	本机结果	状态
Node.js	≥ 22.11	v26.0.0	✅
pnpm	≥ 10	11.8.0	✅
git	有	2.39.5	✅
DevEco Studio	26.x / 6.1.0+	26.0.0	✅
HarmonyOS SDK	API ≥ 17	API 26 (26.0.0.23)	✅
hdc	PATH 中	3.2.0e	✅
RNOH_C_API_ARCH	1	1	✅
HDC_SERVER_PORT	任意	7035	✅
DEVECO_SDK_HOME	CLI 依赖	已设置	✅
npm registry	建议镜像	官方源（连通正常）	✅

本次搭建的机器环境全部达标，无需额外安装；如果你的机器有缺失项，继续看下一节按需安装。

---

4. 安装与配置：DevEco Studio、SDK、hdc、环境变量

如果你的检查结果全是 ✅，可直接跳到第 5 节。

4.1 安装 DevEco Studio（含 OpenHarmony SDK）

1. 从开发工具官网下载安装 DevEco Studio（macOS 默认安装到 /Applications/DevEco-Studio.app）。
2. 打开 DevEco Studio → Preferences → SDK（Windows 为 File → Settings → SDK），勾选 OpenHarmony SDK，确认 API Level 满足版本矩阵要求（0.84 需 API ≥ 17）。
3. 点击 Apply 等待 SDK 下载完成。

⛔ 千万别跳过 SDK 安装——仅装 IDE 是不够的，hdc、编译工具链都在 SDK 里。

4.2 配置 hdc 到 PATH

hdc（OpenHarmony Device Connector）是鸿蒙命令行调试工具，位于 SDK 的 toolchains 目录。macOS 下编辑 ~/.zshrc：

# 将 toolchains 目录加入 PATH（按实际 SDK 路径填写）
export PATH="/Applications/DevEco-Studio.app/Contents/sdk/{SDK版本}/openharmony/toolchains:$PATH"
# 或如果你用的是独立 SDK（如 ~/Library/OpenHarmony/Sdk/26.0.0/toolchains）
export PATH="/Users/nutpi/Library/OpenHarmony/Sdk/26.0.0/toolchains:$PATH"

# HDC 端口（任意未占用端口）
HDC_SERVER_PORT=7035
launchctl setenv HDC_SERVER_PORT $HDC_SERVER_PORT
export HDC_SERVER_PORT

生效后验证：source ~/.zshrc && hdc --version。

⚠️ Windows 用户在「系统环境变量」GUI 中配置后，需要完全重启 VS Code / 终端才能生效（VS Code 启动时会缓存环境变量）。

4.3 配置 RNOH_C_API_ARCH（0.82+ 必需）

CAPI 架构是 RNOH 0.82+ 的默认架构，未设置该变量会导致运行时回退旧架构引发崩溃。macOS 写入 ~/.zshrc：

export RNOH_C_API_ARCH=1

验证：echo $RNOH_C_API_ARCH 应输出 1。

4.4 配置 DEVECO_SDK_HOME（CLI 命令依赖）

react-native run-harmony、bundle-harmony 等 CLI 命令依赖该变量。macOS 默认安装路径下只需设为 SDK 基址：

export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"

macOS 注意：默认安装路径下无需设置 DEVECO_HOME，工具链会自动识别；仅非默认路径才需要。

4.5 （可选）配置 npm 华为云镜像

中国大陆网络环境下 npm install 走官方源容易超时，可在 ~/.npmrc 配置华为云镜像：

registry=https://repo.huaweicloud.com/repository/npm/

⚠️ 不要全局关闭 strict-ssl / sslVerify（有中间人攻击风险）；仅在个别包 SSL 报错时对镜像域名单独关闭。
修改后执行 npm cache clean --force 清缓存。

---

5. 创建 React Native 工程

使用社区 CLI 初始化工程，版本必须传 0.84.1（RNOH 0.84.3 对应的 react-native 版本，npx react-native init 已废弃）：

# 在目标目录下执行；--skip-install 可跳过 iOS 依赖下载（mac 下耗时较长，鸿蒙开发用不到）
npx @react-native-community/cli@latest init AwesomeProject --version 0.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.3）：

npm install @react-native-oh/react-native-harmony@0.84.3 @react-native-oh/react-native-harmony-cli@0.84.3

验证安装：

node -e "console.log(require('./node_modules/@react-native-oh/react-native-harmony/package.json').version)"
# 0.84.3

6.2 修改 package.json：添加 bundle 命令

在 scripts 下新增 dev 脚本，用于生成鸿蒙 bundle：

   "scripts": {
     "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}
 */
const config = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

module.exports = mergeConfig(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
        templateFileName="App.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-harmony）

RNOH 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" directory

harmony/ 目录结构：

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（指向本地 har）

7.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.path getter 依赖 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 的兼容问题
const fs = require('node:fs');
const origReaddirSync = fs.readdirSync;

fs.readdirSync = function (p, options) {
  const result = origReaddirSync.apply(this, arguments);
  const opts = typeof options === 'object' && options !== null ? options : undefined;
  if (opts && opts.withFileTypes && Array.isArray(result)) {
    const base = typeof p === 'string' ? p : String(p);
    for (const dirent of result) {
      if (!('path' in dirent)) {
        Object.defineProperty(dirent, 'path', {
          value: base,
          configurable: true,
          enumerable: true,
        });
      }
    }
  }
  return result;
};

带 shim 重新执行即可：

NODE_OPTIONS="-r ./shim-dirent-path.js" npx react-native init-harmony \
  --bundle-name com.awesomeproject.app --app-name AwesomeProject

---

8. 生成 bundle 并验证

8.1 生成 bundle

运行 npm run dev（即 react-native bundle-harmony --dev），把 RN 侧代码打包成鸿蒙可加载的 bundle：

npm run 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 -lh harmony/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 服务即可：

npm start

RNOH 壳工程的 jsBundleProvider 默认优先尝试 MetroJSBundleProvider（见 harmony/entry/src/main/ets/pages/Index.ets），再回退到本地 bundle 文件。

---

9. 在 DevEco Studio 中运行到真机

1. 用 DevEco Studio 打开 AwesomeProject/harmony 目录，等待后台任务（ohpm install / SyncData / 首次全量编译 C++）完成——首次全量编译耗时较长，请耐心等待。
2. 点击右上角用户图标 → Sign in 登录华为账号。
3. 连接真机（USB 调试，可通过 hdc list targets 确认设备已连接）。
4. File > Project Structure > Signing Configs，勾选 Automatically generate signature，点击 OK 自动签名。
5. 选择 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] TypeError	Node 26 下 fs.Dirent.path 缺失	使用文中的 shim-dirent-path.js 补丁
Bundle name validation failed	bundle-name 不是三段式	传 com.org.project 形式（含两个点）
运行白屏	App.tsx 依赖 safe-area-context / appKey 与注册名不一致	替换 App.tsx（见 6.4）；核对 app.json name
RNOH_C_API_ARCH 未设置崩溃	0.82+ 默认 CAPI 架构	export RNOH_C_API_ARCH=1 并写入 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-harmony@0.84.3）
  → 配置 metro.config.js + package.json
  → init-harmony 生成鸿蒙壳工程
  → npm run dev 生成 bundle
  → DevEco Studio 签名并运行到真机

要点回顾：

1. 版本对应关系是最大的坑：RNOH 0.84.3 的 RN 基座是 0.84.1，初始化与依赖安装的版本要分开看；
2. 环境变量要提前配齐：RNOH_C_API_ARCH=1（必需）、HDC_SERVER_PORT、DEVECO_SDK_HOME、hdc 的 PATH；
3. Node 26 兼容问题用 preload shim 即可绕过，不影响项目本身；
4. 白屏问题绝大多数是 safe-area-context 依赖或 appKey 不一致导致。

配置好一次环境后，后续新项目只需：init → 装依赖 → 改 metro/package.json → init-harmony → npm run dev → DevEco 运行，五分钟即可跑通一个新 RNOH 工程。

---

本文基于 React Native鸿蒙化仓库 官方文档与真实搭建过程整理，版本信息以 版本说明 为准。

欢迎大家关注React Native鸿蒙化仓库社区。