React Native鸿蒙跨平台开发实战：从搭建环境到仪表盘落地

如果你跟我一样，手里已经有一套跑得好好的 React Native 项目，某天被拉去要求适配鸿蒙，第一反应多半不是兴奋，而是胃疼。重写 ArkTS？两套代码库同步维护？还是说，真有办法让 RN 代码直接在鸿蒙上跑起来？

这篇文章记录的就是后面这条路的实际落地过程——用 React Native 鸿蒙跨平台开发方案，做一个模拟汽车仪表盘。项目本身不算复杂，但真正走一遍才发现，环境搭建、启动白屏、模拟器架构限制这些问题，每一个都能卡住大半天。文章会把整个流程、关键代码、以及我排查问题时的完整链路都摊开讲，适合已经熟悉 RN、但对鸿蒙跨平台开发还比较陌生的朋友参考。

需要提前说明的是，鸿蒙开发环境迭代很快，文中涉及的版本号和数据以实际下载时官方最新版本为准，我更侧重讲清楚思路和坑点，这些不会过时。

1. 为什么用 React Native 做鸿蒙跨平台：一次选型复盘

1.1 从一次真实需求说起

我们团队有一个已经上线几年的 React Native 应用，覆盖 Android 和 iOS。业务方提需求时直接问：鸿蒙版本什么时候能上？如果走纯 ArkTS 重写，等于把核心业务逻辑在另一个技术栈里再实现一遍，后续每次产品迭代都是双倍工作量，而且两套代码的业务规则很难保证完全一致。

最理想的状态，是复用现有 RN 组件代码，把鸿蒙当成一个新的渲染目标。这里就需要引入 React Native for OpenHarmony，也就是常说的 RNOH。它做的事情，是把 React Native 的运行时、Fabric 渲染管线、核心组件逐一移植到 OpenHarmony 系统上，让 RN 的 JS 代码可以直接调用鸿蒙侧的原生能力。

1.2 三条路线的对比

我在做技术选型时，把可行方案列了一张表：

对我们这种 RN 存量团队，RNOH 明显是性价比最高的。它的原型项目已经支持大量核心组件和 API，目前社区也在持续补齐第三方的组件适配。需要注意的是，第三方的 RN 原生模块（比如地图、推送、支付）不一定都支持鸿蒙，选型前必须逐个确认自己用到的依赖有没有鸿蒙版本，这一步不能省。

1.3 RNOH 到底改了什么

理解 RNOH 之前，要先理解 RN 在 Android/iOS 上的运行方式：JS 层通过 JSI（JavaScript Interface）和原生层通信，原生层使用各自平台的渲染引擎生成 UI。RNOH 做的事情，是把这套 JSI 桥接到 OpenHarmony 的 ArkUI 上。

具体来说，RNOH 项目会在鸿蒙侧提供一个 Harmony 原生模块，把 RN 的根视图挂载到 ArkUI 的组件树中。JS 组件经过 React Reconciler 处理后，不是直接渲染成 View 层级，而是通过 C++ 层的 Fabric Renderer 映射到 ArkUI 的自定义组件上。这就是为什么 RN 的布局、样式逻辑在鸿蒙上基本不需要改动，但某些底层 API（比如原生传感器、蓝牙）需要鸿蒙专属实现。

JS 引擎方面，RNOH 同时支持 Hermes 和鸿蒙的方舟 JSVM。如果你在构建时选择了 JSVM，要注意它是 ARM64 优先的，这在后面模拟器环节会是一个重要限制。我一开始没有注意到这个细节，导致在模拟器上折腾了很久，后面专门有一节讲这个问题。

2. 搭建 RNOH 开发环境：版本对齐是第一道坎

2.1 工具链清单

既然是环境搭建，先把要准备的东西列全。

2.2 初始化 RNOH 项目的完整过程

先在终端创建项目，我用的是官方 CLI：

bash复制npx @react-native-oh-tpl/cli@latest init CarDashboard
cd CarDashboard
npm install

执行完命令后，会看到项目结构和普通 RN 项目最大的区别：多了一个 harmony 目录。这个目录就是鸿蒙工程，里面是 DevEco Studio 能直接识别的工程结构。后续所有原生侧代码、权限配置、依赖声明都在这里改。

接着，用 DevEco Studio 打开