Filge前阵子接到一个项目，要求把一部分已有业务从 Android 侧平滑迁到鸿蒙（HarmonyOS）上，同时还要兼顾团队现有的 React Native 技术栈。调研了一圈后发现，直接在鸿蒙上用 ArkTS 重写全部业务成本太高，于是我们走了“React Native 渲染 + 鸿蒙原生组件下沉”的混合路线。这条路踩了不少坑，但也把关键技术链路摸清楚了。这篇就专门聊聊：在 React Native 项目里开发鸿蒙组件，到底该怎么落地。
不管你是刚开始接触鸿蒙的前端同学，还是已经在 DevEco Studio 里写过几个 Demo 的客户端开发，“RN 怎么调鸿蒙原生能力”“鸿蒙的 har/hsp/hap 到底怎么和 RN 工程配合”这些话题，应该都能从我这里找到一些可参考的答案。我会尽量把环境搭建、工程配置、组件封装、打包发布到问题排查整个链路都讲透，确保看完了能动手。
1. 先想清楚：React Native 和鸿蒙是怎么“兼容”到一起的
1.1 核心认知：是“适配层”，不是“重新实现”
很多人第一次听说 React Native 能开发鸿蒙组件时，第一反应是“RN 不是只能跑在 Android 和 iOS 上吗？”确实，RN 官方目前没有正式支持鸿蒙，但社区早就有了一套非常成熟的适配方案——react-native-harmony，它由 OpenHarmony SIG 持续维护，核心思路不是给鸿蒙写一套新的 JS 引擎，而是在鸿蒙系统上增加一个 RN 运行时层，让 JS 代码最终渲染到鸿蒙的 ArkUI 组件体系上。
打个比方：RN 在 Android 上负责把 JSX 映射成 Android View，在 iOS 上映射成 UIView，而在鸿蒙这里，它映射成 ArkUI 的组件。用户看到的界面是鸿蒙原生的，摸起来的手感也是鸿蒙原生的，但业务逻辑、页面路由、状态管理全都跑在 JS 层。这就意味着团队里现有 RN 代码不用推翻重写，只需要在需要深度系统能力的地方，通过“原生模块 + 原生组件”的方式，把鸿蒙的能力暴露给 JS 调用。
这里一定要区分两个概念：
- React Native 应用包：通过 RN 框架打包出来的 JS Bundle 和鸿蒙原生壳工程合成的 App。
- 鸿蒙原生组件/模块：用 ArkTS 写的、运行在鸿蒙系统上的原生能力单元，RN 侧通过桥接层调用。
在实际工程里，它们是两个既独立又耦合的部分。理解这个关系后，后面所有环境配置和代码组织就都不绕了。
1.2 为什么选择“RN 壳 + 鸿蒙原生组件”混合方案
项目选型时通常有三种思路：纯 ArkTS 重写、RN 全量迁移、RN + 鸿蒙原生混合。纯 ArkTS 重写在业务量小且团队熟悉鸿蒙时最干净，但大多数团队的问题是业务逻辑集中在 JS 层，重写成本太高。RN 全量迁移呢，看起来省事，但实际上总会撞上一些必须走系统 API 的场景，比如推送、扫码、安全存储、硬件通信，这些在 RN 生态里没有现成库里只能自己写原生。
最终的折中方案就是“RN 主业务 + 鸿蒙原生组件下沉”：页面尽量在 RN 层写，碰到没法用通用库解决的系统能力，就用鸿蒙 ArkTS 封装成原生模块；如果某个页面交互特别复杂、强依赖系统控件和手势，那就直接用鸿蒙原生页面承载，通过路由参数和 RN 页面互相跳转。这个方案的最大好处是渐进式迁移，一次只迁移一个业务模块，哪怕上线后发现某个模块有问题，也可以随时切回 RN 版本，不至于伤筋动骨。
从团队角度来看，这个方案对人员技能要求也友好得多：前端工程师继续写 JS/TypeScript，客户端工程师只需要把精力放在原生模块封装和性能优化上，两边不用互相等。
1.3 技术链路全景：从 JS 到 ArkUI 的一次完整旅程
日常开发时，一次最简单的“RN 页面点击按钮 -> 调用鸿蒙原生能力 -> 返回结果渲染到界面”，底层链路其实是这样的：
- RN 侧 JS 代码通过
NativeModules或 TurboModule 发起调用。 - 调用进入 react-native-harmony 的适配层，适配层把调用路由到对应的 ArkTS 原生模块。
- ArkTS 原生模块执行真正的系统逻辑（比如读取剪贴板、初始化扫码、调用蓝牙）。
- 执行结果通过 Promise 或 Callback 原路返回 JS 层。
- JS 层拿到数据后 setState，触发 UI 更新，最终刷新 ArkUI 渲染树。
链路本身不复杂，但每一步都有值得注意的细节。比如第 2 步的 TurboModule 注册方式、第 3 步的装饰器使用、第 5 步的状态同步，都会直接决定功能能不能跑通、性能好不好。后面我会逐一拆开讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境与工程搭建：HarmonyOS + RN 双端联动
2.1 开发环境清单与版本匹配
这部分直接给你一套我验证过多次的组合，照着装基本不会出问题：
| 软件 | 推荐版本 | 说明 |
|---|---|---|
| Node.js | 18 LTS 或 20 LTS | RN 构建和 Metro 服务必需，老项目注意看自家 package.json 要求 |
| JDK | 17 | DevEco Studio 和 Gradle 构建链需要，别用 11 或 21 代替，会有兼容性问题 |
| DevEco Studio | 5.0.x 及以上 | 鸿蒙官方 IDE，创建工程和打包 hap 都靠它 |
| HarmonyOS SDK | API 12 及以上 | 对应 DevEco 内置 SDK，项目编译时需要 |
| react-native | 0.72 或 0.73 | 根据 react-native-harmony 的版本适配表选择，不要盲目上新版 |
| react-native-harmony | 0.72.x 或 0.73.x | 要和 RN 大版本严格对应，错一个版本都跑不起来 |
版本匹配是第一个大坑。react-native-harmony 的发布准则是“跟随 RN 版本”，比如 react-native-harmony@0.72.x 就对应 RN 0.72 系列。我见过不少同学直接 npm install react-native-harmony@latest，结果和本地的 RN 版本对不上，编译时报一堆 .so 找不到的错误。建议初始化工程前，先去 GitHub 的 react-native-harmony Relea