Windows 平台 React Native OpenHarmony（鸿蒙）开发环境搭建指南：从源码克隆到鸿蒙 PC 真机运行（含 Submodule 依赖、设备类型适配与离线 Bundle 部署）

wei_shuo

21人浏览 · 2026-09-15 09:28:12

wei_shuo · 2026-09-15 09:28:12 发布

Windows 平台 React Native OpenHarmony（鸿蒙）开发环境搭建指南：从源码克隆到鸿蒙 PC 真机运行（含 Submodule 依赖、设备类型适配与离线 Bundle 部署）

基于 react-native-harmony 仓库 0.86.1 版本（对齐上游 React Native 0.86.3）在 Windows 10 22H2 上全程实测通过；真机环节在一台鸿蒙 PC（OpenHarmony 6.1.1，API 24，arm64，2in1 形态）上验证。文中所有命令输出、报错信息、坑位均为真实环境抓取，可放心对照复现。

在这里插入图片描述

前言

React Native 官方并不支持鸿蒙（OpenHarmony/HarmonyOS），目前主流方案是由 OpenHarmony 社区维护的 React Native for OpenHarmony（RNOH） 适配层。通过它，你可以用熟悉的 React/React Native 技术栈直接开发鸿蒙应用，享受 JS 热更新、组件化开发、Metro 打包等完整体验。

但这个环境的搭建体验对新手同样不友好：必须通过 git clone 获取源码（ZIP 下载会丢失 C++ 第三方依赖的 submodule，CMake 编译直接报错）；初始化流程涉及 submodule 更新、pnpm 依赖安装、上游代码同步、hvigor 插件构建四个串联步骤，任何一步遗漏都会导致后续编译失败；就算环境全绿，在鸿蒙 PC 上运行还有设备类型不匹配、Metro 连接失败、离线 Bundle 加载等典型问题等着你。本文把完整流程 + 全部坑位的现象、根因、修复方法一次讲清，小白照着做即可一次跑通。

📖 官方环境搭建文档：本文基于 RNOH 官方文档整理，补充了鸿蒙 PC（2in1）真机实测细节。如需查阅官方版本，请参考 RNOH 环境搭建指南。

一、环境准备：软件清单与目录规划

1.1 软硬件要求

项目	要求
操作系统	Windows 10 / 11（本文实测 Windows 10 22H2）
磁盘空间	30GB 以上（源码 + node_modules + C++ 编译产物 + DevEco Studio）
网络	能访问 GitHub（submodule 全在 GitHub 上，需确保网络连通）

1.2 软件安装清单

软件	实测版本	作用	获取方式
DevEco Studio	26	鸿蒙官方 IDE，自带 HarmonyOS SDK、ohpm、hvigor、hdc 工具链	华为开发者官网
Git	2.50.0	源码克隆与 submodule 管理	git-scm.com
Node.js	v22.17.1（推荐 v18 LTS）	pnpm、hvigor、Metro 均为 Node 程序	nodejs.org
pnpm	10.3.0	项目指定的包管理器（版本严格校验）	npm install -g pnpm@10.3.0

版本说明：pnpm 版本必须严格匹配 10.3.0（项目配置了 package-manager-strict-version=true），否则 pnpm i 会直接报错。Node.js 版本推荐使用 18 LTS，v22 在部分 native addon 场景下可能有兼容性问题，但本文实测 v22.17.1 可正常完成全流程。

1.3 关键前提：所有路径必须为纯英文

这是本文最想让你记住的一条，血的教训：

源码的存放路径、工程项目的存放路径，绝对不能包含中文。
hvigor（鸿蒙构建系统）对路径有字符白名单校验，只允许字母、数字、-、_、.、空格、()、@。
中文路径在前期步骤完全正常（所以你发现不了问题），直到 DevEco 编译 C++ 时才报错，非常隐蔽。

本文统一使用以下示例路径（请按需替换，但务必保持纯英文）：

源码目录：D:\RNS\ohos_react_native
DevEco 安装：D:\DevEco Studio 26\DevEco Studio

二、安装 DevEco Studio（含完整工具链）

从华为开发者官网下载安装包，一路默认安装。本文实测安装在 D:\DevEco Studio 26\DevEco Studio（注意：安装完可能是两层同名目录，下文以此为准，请你记准自己的实际安装路径）。
首次启动按引导完成配置（主题、协议等一路下一步即可）。SDK 会随 IDE 自动就位。
验证安装结果——打开目录 D:\DevEco Studio 26\DevEco Studio，应能看到这些关键子目录：

D:\DevEco Studio 26\DevEco Studio
├── tools\
│   ├── ohpm\bin\          ← 鸿蒙包管理器（类似 npm）
│   └── hvigor\bin\        ← 鸿蒙构建系统（类似 gradle）
└── sdk\
    └── default\           ← HarmonyOS SDK
        ├── hms\
        └── openharmony\toolchains\   ← hdc 设备调试工具在这里

三、获取 RNOH 源码：必须 Git Clone

这是整个环境搭建最重要的一步。 RNOH 项目通过 git submodule 管理 9 个 C++ 第三方依赖库，ZIP 下载的源码不包含这些依赖的实际内容（只有空目录），后续 CMake 编译会直接报错。

3.1 为什么不能用 ZIP 下载？

项目根目录的 .gitmodules 文件真实内容如下：

[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/boost"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/boost
    url = https://github.com/boostorg/boost.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fmt"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fmt
    url = https://github.com/fmtlib/fmt.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/folly"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/folly
    url = https://github.com/facebook/folly.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/double-conversion"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/double-conversion
    url = https://github.com/google/double-conversion.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/glog"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/glog
    url = https://github.com/google/glog.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/libevent"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/libevent
    url = https://github.com/libevent/libevent.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fast_float"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fast_float
    url = https://github.com/fastfloat/fast_float.git
[submodule "packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/hermes"]
    path = packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/hermes
    url = https://github.com/facebook/hermes.git
[submodule "packages/react-native"]
    path = packages/react-native
    url = https://github.com/facebook/react-native

这 9 个 submodule 全部托管在 GitHub 上。ZIP 下载只包含主仓库代码，submodule 目录是空的——CMake 编译时找不到 fmt/CMakeLists.txt、boost/CMakeLists.txt 等文件，直接报错。

3.2 Git Clone（唯一正确方式）

# 克隆主仓库
git clone https://atomgit.com/CPF-RN/ohos_react_native

如果 Gitee 镜像速度不理想，也可以用 GitHub 源。克隆完成后，不要急着往下走——还需要更新 submodule。如果你的网络访问 GitHub 不稳定，先配置网络参数（下一节）。

3.3 配置 Git 网络参数（按需）

submodule 全部在 GitHub 上，如果网络访问 GitHub 不稳定，可以为 GitHub 单独配置网络加速（不影响其他仓库）：

# 仅对 github.com 走加速通道（假设你的本地转发端口是 7897）
git config --global http.https://github.com.proxy http://127.0.0.1:7897
git config --global https.https://github.com.proxy http://127.0.0.1:7897

注意：不要用 git config --global http.proxy 设置全局加速，那会影响所有 Git 仓库。按 URL 精确配置，只在访问 GitHub 时走加速，其他仓库不受影响。端口号根据你实际使用的网络工具填写（常见端口如 7890、10809 等，请参照工具设置确认）。

3.4 更新 Submodule

cd D:\RNS\ohos_react_native
git submodule update --init --recursive --progress --jobs 16

首次执行会克隆 9 个 GitHub 仓库，耗时取决于网络（通常 5~15 分钟）。成功后的预期输出：

Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/boost'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fmt'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/glog'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/folly'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/hermes'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/libevent'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/double-conversion'...
Cloning into 'D:/RNS/ohos_react_native/packages/tester/harmony/react_native_openharmony/src/main/cpp/third-party/fast_float'...
Cloning into 'D:/RNS/ohos_react_native/packages/react-native'...
Submodule path ...: checked out 'xxxxxxxx'

看到所有 submodule 都 checked out 就对了。

四、初始化工作区：四步串联流程

Submodule 就位后，还需要完成四个串联步骤。项目提供了一键命令：

cd D:\RNS\ohos_react_native
pnpm init-ws

这条命令实际依次执行四个步骤。如果一键命令在某一步失败（比如网络中断），可以拆开手动执行：

4.1 步骤一：更新 Submodule（已在第三章完成）

git submodule update --init --recursive --progress --jobs 16

4.2 步骤二：安装 JS 依赖

pnpm i

项目根目录的 .npmrc 真实配置：

@ohos:registry=https://repo.harmonyos.com/npm
node-linker=hoisted
package-manager-strict-version=true
package-manager-strict=true
manage-package-manager-versions=true

关键配置解读：@ohos:registry 指向华为鸿蒙官方 npm 源——@rnoh/react-native-openharmony 等鸿蒙专属包只发布在这个源上。package-manager-strict-version=true 强制要求 pnpm 版本必须精确匹配 package.json 中声明的 10.3.0。

预期输出：

Scope: all 12 workspace projects
Lockfile is up to date, npm install: No workspaces to install
.pnpm/...: Resolving packages
...
Done in 2m 30s

安装完成后会触发 postinstall 钩子设置 husky（Git hooks），如果 husky 设置失败不影响后续流程。

4.3 步骤三：集成上游代码

pnpm run _integrate-upstream-code

这一步做的事情：

应用 boost.patch（boost 库的鸿蒙适配补丁）
将 packages/react-native（上游 React Native submodule）的 ReactCommon、Libraries、src/types 等目录同步到 react_native_openharmony 的对应位置
生成 build-profile.json5（从模板文件生成鸿蒙项目配置）

预期输出：

Applying boost.patch...
Synchronizing ReactCommon...
Synchronizing delegates...
Synchronizing Libraries...
Synchronizing src/types...

4.4 步骤四：构建 hvigor 插件

cd packages/react-native-harmony-cli
pnpm _recreate-hvigor-plugin

这一步构建鸿蒙专属的 hvigor 构建插件（.tgz 包），DevEco 编译时依赖它。

预期输出：

PASS  src/__tests__/...
Tests: 6 passed, 6 total
...
rnoh-hvigor-plugin-0.86.1.tgz

6 个测试全部通过后，packages/react-native-harmony-cli/harmony/rnoh-hvigor-plugin-0.86.1.tgz 生成。

五、配置环境变量

5.1 设置 RNOH_C_API_ARCH

这是鸿蒙 PC（2in1）编译的必要环境变量，不设置会导致 C++ 编译失败。

Win + R 输入 sysdm.cpl 回车 → 「高级」选项卡 → 「环境变量(N)…」。

在**下半栏"系统变量"**中点「新建(N)…」：

变量名	变量值	作用
RNOH_C_API_ARCH	1	启用 C API 架构（鸿蒙 PC 编译必需）

变量级别选"系统变量"（下半栏）或"用户变量"（上半栏）均可。设置完成后新开终端窗口才生效。

5.2 确认 Path 中的工具链

DevEco Studio 安装后，以下工具应该已经在 PATH 中（如果没有，手动添加）：

#	Path 条目	来源
1	D:\DevEco Studio 26\DevEco Studio\tools\ohpm\bin	ohpm 包管理器
2	D:\DevEco Studio 26\DevEco Studio\tools\hvigor\bin	hvigor 构建系统
3	D:\DevEco Studio 26\DevEco Studio\sdk\default\openharmony\toolchains	hdc 设备调试工具

5.3 验证环境

新开一个 PowerShell 窗口，逐条验证：

node --version       # 预期：v22.17.1 或 v18.x.x
pnpm --version       # 预期：10.3.0
ohpm --version       # 预期：26.0.0.630 或类似版本
hdc -v               # 预期：hdc version ...
echo $env:RNOH_C_API_ARCH  # 预期：1

五项全部有输出，环境就绑定好了。

六、在 DevEco Studio 中打开项目

6.1 打开正确的目录

关键：DevEco 要打开的不是源码根目录，而是 tester 的 harmony 子目录：

D:\RNS\ohos_react_native\packages\tester\harmony

DevEco Studio → 「文件」→「打开」→ 选择上述路径 → 等待右下角工程同步（Sync）完成。

首次 Sync 会执行 ohpm 依赖安装和 hvigor 项目解析，通常需要 2~5 分钟。Sync 完成后，左侧项目树应能看到 entry、react_native_openharmony、sample_package 等模块。

6.2 鸿蒙 PC 设备类型适配（2in1 必做）

如果你要在鸿蒙 PC（2in1 设备）上运行，必须修改 entry 模块的设备类型声明。

编辑 packages\tester\harmony\entry\src\main\module.json5，将 deviceTypes 补全：

"deviceTypes": [
  "default",
  "2in1"
],

为什么必须改：DevEco 检测到目标设备是鸿蒙 PC 后，会通过 -p requiredDeviceType=2in1 参数传给 hvigor 校验。而模板默认只声明了 “default”，hvigor 会直接报错：
Error Message: The type of target device does not match the device type configured by module: entry.
Required device type:2in1, current module device type:default
加上 “2in1” 即可。如果是手机/平板，则加 “phone” / “tablet”。建议多设备形态全声明：[“default”, “phone”, “tablet”, “2in1”]。

6.3 编译运行

在 DevEco 顶部 Run 配置下拉框选择 entry，点击 Run（绿色三角按钮）。

首次编译会编译大量 C++ 原生代码（boost、fmt、glog、folly、hermes、ReactCommon 等），耗时 15~30 分钟属正常现象。Build 窗口会持续滚动 [xxx/yyy] Building CXX object … 日志，耐心等待即可。

编译成功后，app 自动安装到鸿蒙 PC 上。

七、JS Bundle 加载：离线 Bundle 方案

7.1 问题背景

编译安装成功后，app 启动时会尝试加载 JS Bundle。RNOH 的 JSBundleProvider 有两种加载策略：

从 Metro 开发服务器加载（需要网络连接）
从设备本地文件加载（bundle.harmony.js）

在鸿蒙 PC（2in1）上，由于 HarmonyOS 沙箱隔离，app 默认无法直接通过 localhost:8081 访问宿主机上的 Metro 服务。hdc rport 端口转发也会因为 Metro 本身占用了 8081 端口而冲突：

$ hdc rport tcp:8081 tcp:8081
[Fail]TCP Port listen failed at 8081

7.2 解决方案：打包离线 Bundle

最可靠的方案是直接打包离线 Bundle，让 app 从本地文件加载：

cd D:\RNS\ohos_react_native\packages\tester
npx react-native bundle-harmony --dev false --entry-file index.js

预期输出：

Welcome to Metro v0.84.3
              Fast - Scalable - Integrated

[INFO] Redirected imports to 3 harmony-specific third-party package(s):
[INFO] • react-native-fs → @react-native-ohos/react-native-fs
[INFO] • react-native-safe-area-context → @react-native-ohos/react-native-safe-area-context
[INFO] • react-native-sample-package → react-native-harmony-sample-package

info Created harmony\entry\src\main\resources\rawfile\bundle.harmony.js
info Copied 18 assets

Bundle 文件生成在 harmony\entry\src\main\resources\rawfile\bundle.harmony.js，DevEco 编译时会自动将其打入 HAP 包。

7.3 重新安装

打包完成后，回到 DevEco 重新 Run entry。app 安装后直接从本地加载 Bundle，无需 Metro 服务。

7.4 运行效果

成功启动后，RN Tester 主界面显示：

RN Tester (C_API)                    RN 0.86.3

Internet connected: true
Driver initialized: false

CONCURRENT TESTER
CONCURRENT TESTER: DEV
SEQUENTIAL TESTER [driver required]
SEQUENTIAL TESTER: DEV
AccessibilityInfo
ActionSheetIOS
ActivityIndicator
Alert
Animated
...

Internet connected: true — 网络正常
Driver initialized: false — 正常，2in1 设备无硬件驱动
点击任意测试模块（如 ActivityIndicator、Alert）即可验证对应组件

后续改代码的迭代流程：修改 JS 代码后，重新执行 npx react-native bundle-harmony --dev false --entry-file index.js，然后在 DevEco 重新 Run 安装 app。虽然不如 Metro 热更新方便，但在 2in1 设备上这是最稳定的方式。

八、故障排查 FAQ：六大核心问题

以下六条核心 FAQ 按环境搭建的阶段顺序排列，你可以根据自己卡住的环节直接对号入座。

Q1（源码获取）：CMake 报错找不到 C++ 第三方库

现象：DevEco 编译时 CMake 报：

CMake Error: The source directory
  D:/.../third-party/fmt
does not contain a CMakeLists.txt file.

fmt、glog、boost、double-conversion、fast_float 等目录全部报同样的错，ReactCommon 下的 30+ 子目录也显示不存在。

根因：源码是通过 ZIP 下载的，不是 git clone。ZIP 不包含 submodule 的实际内容，只有空目录壳。

解决：必须用 git clone 获取源码，然后执行 git submodule update --init --recursive。没有捷径。如果已经用 ZIP 开始了，删掉重来：

# 删掉旧的 ZIP 源码
Remove-Item -Recurse -Force D:\RNS\ohos_react_native

# 重新克隆
git clone https://atomgit.com/CPF-RN/ohos_react_native.git D:\RNS\ohos_react_native
cd D:\RNS\ohos_react_native
git submodule update --init --recursive --progress --jobs 16

Q2（源码获取）：git submodule update 连接 GitHub 超时

现象：

fatal: unable to access 'https://github.com/boostorg/boost.git/': Failed to connect to github.com port 443 after 21048 ms

根因：国内网络访问 GitHub 不稳定。

解决：为 GitHub 单独配置网络加速（假设本地转发端口 7897）：

git config --global http.https://github.com.proxy http://127.0.0.1:7897
git config --global https.https://github.com.proxy http://127.0.0.1:7897

然后重新执行 git submodule update --init --recursive。

Q3（依赖安装）：pnpm install 报版本不匹配

现象：

ERROR  This project is configured to use pnpm 10.3.0
Your pnpm version is 9.x.x

根因：项目 .npmrc 配置了 package-manager-strict-version=true，强制要求 pnpm 版本精确匹配。

解决：

npm install -g pnpm@10.3.0

Q4（编译阶段）：DevEco 编译报设备类型不匹配

现象：

hvigor ERROR: 00303214 Configuration Error
Error Message: The type of target device does not match the device type configured by module: entry.
Required device type:2in1, current module device type:default

根因：鸿蒙 PC 是 2in1 设备类型，但 entry 模块的 module.json5 只声明了 “default”。

解决：编辑 entry\src\main\module.json5，在 deviceTypes 数组中加上 “2in1”：

"deviceTypes": [
  "default",
  "2in1"
],

Q5（运行阶段）：app 启动后报 “None of the provided JSBundleProviders was able to load a bundle”

现象：app 安装成功，启动后红屏报错：

None of the provided JSBundleProviders was able to load a bundle

Suggestions:
1. Is Metro server running? Did you run `react-native start`?
2. Try forwarding data from a device port to a host port (hdc rport tcp:8081 tcp:8081)
3. Are you testing on a real device? Did you connect it to your computer?
4. Check if a bundle exists at "bundle.harmony.js" on your device.

根因：鸿蒙 PC（2in1）上，app 运行在 HarmonyOS 沙箱中，无法直接通过 localhost:8081 访问宿主机上的 Metro 服务。而 hdc rport tcp:8081 tcp:8081 端口转发会失败，因为 Metro 本身已经占用了宿主机的 8081 端口，hdc 无法在设备侧重复绑定同一端口。

解决：打包离线 Bundle（见第七章 7.2 节），让 app 从本地文件加载。这是鸿蒙 PC 上最稳定的方案。

Q6（编译阶段）：首次编译耗时特别长

现象：DevEco 点 Run 后，Build 窗口持续输出 C++ 编译日志，看起来像是卡住了。

根因：首次编译需要编译 RNOH 的全部 C++ 原生代码，包括 boost（部分 header-only 库）、fmt、glog、folly、hermes 引擎、ReactCommon（yoga 渲染引擎、JSI、cxxreact 等 30+ 模块），总计数千个编译单元。

解决：正常现象，耐心等待。首次编译 15~30 分钟属正常范围，取决于 CPU 性能。后续增量编译会快很多（只重编修改过的文件）。Build 窗口有进度在走（百分比在变、日志在滚动）就说明一切正常。

九、总结与下一步

回顾整个流程，其实主线只有六步：

装 DevEco Studio（自带 SDK 和全套工具链）；
git clone 获取 RNOH 源码（必须 clone，不能 ZIP）；
git submodule update --init --recursive 拉取 9 个 C++ 第三方库（需要访问 GitHub）；
pnpm init-ws 一键初始化（安装依赖 + 同步上游代码 + 构建 hvigor 插件）；
系统变量设置 RNOH_C_API_ARCH=1，DevEco 打开 packages\tester\harmony，deviceTypes 补 “2in1”；
打包离线 Bundle → DevEco Run → RN Tester 主界面出现。

再加上三条铁律：路径全英文、源码必须 git clone（ZIP 没有 submodule）、鸿蒙 PC 用离线 Bundle 而非 Metro，就能避开 95% 的坑。

环境搭好之后，你的下一步大概率是开发自己的 React Native 鸿蒙应用。建议从 RNOH 官方文档的开发指南入手，了解 TurboModule、Fabric Component 等核心概念；如果需要集成三方库，参考示例工程中的 AutolinkingSample 和 FabricComponentSample。

开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

关于开源鸿蒙OTA升级和自动安装

开源鸿蒙（OpenHarmony）支持 OTA 升级，并且可以通过配置实现自动安装。