技术解读：Windows 平台 React Native OpenHarmony（鸿蒙）开发环境搭建指南：从源码克隆到鸿蒙 PC
基于 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 加载 等典型问题等着你。本文把完整流程 + 全部坑位的 现象、根因、修复方法 一次讲清，小白照着做即可一次跑通。
一、环境准备：软件清单与目录规划
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 单独配置网络加速（不影响其他仓库）：
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
@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 pnpm -- version ohpm -- version hdc - v echo $env :RNOH_C_API_ARCH
六、在 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 开始了，删掉重来：
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 上最稳定的方案。
现象 ：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。
📖 官方环境搭建文档 ：补充了鸿蒙 PC（2in1）真机实测细节。如需查阅官方版本，请参考 RNOH 环境搭建指南 。
转载声明：本文为转载整理，原文版权归原作者及原站点所有。
原文来源：CSDN HarmonyOS
原创地址：https://blog.csdn.net/weixin_62765017/article/details/165437697
原文作者：wei_shuo；如有侵权，请联系管理员删除。
