React Native 圈子最近聊得最多的话题绕不开鸿蒙HarmonyOS。我去年接到公司需求——把一款纯 RN 写的业务 App 跑在鸿蒙设备上而原生团队根本抽不出人去重写 ArkTS 版本唯一现实的路就是让 RN 和鸿蒙组件共存在复用现有 JS 业务代码的同时把鸿蒙系统能力一点一点接进来。折腾了小半年踩过启动白屏、回调丢失、构建翻车这些坑之后我终于把这套“RN 鸿蒙”的混合工程跑稳了。这篇就写给同样准备接鸿蒙组件的 RN 开发者把技术基础、集成步骤和真实项目里最容易出问题的地方一次性讲透。文章会涉及一点鸿蒙开发的基础概念但不会让你去啃整套官方文档你只需要理解 ArkTS、ArkUI、Stage 模型这三块就能在 RN 工程里写自己的鸿蒙原生模块。如果你连鸿蒙都没碰过也没关系按着文中的路径走第一周就能看到一个能跑的 Demo。1. 先想清楚React Native 和鸿蒙到底是什么关系1.1 别把鸿蒙当成“安卓换皮”很多 RN 开发者一开始都会有个错觉鸿蒙不是能直接跑 APK 吗那我的 RN App 是不是拿安卓包直接装上就行现实没这么简单。早期兼容安卓应用的鸿蒙版本确实能跑 APK但那是通过系统兼容层模拟了安卓的运行时环境。从应用开发的角度看鸿蒙现在的官方原生开发路径是 ArkTS ArkUI Stage 模型这套东西和 Android SDK 完全不是一个技术栈。你在 Android 上用的 Activity、Fragment、XML 布局在鸿蒙里对应的是 UIAbility、Page 和声明式 UI你在 RN 里熟悉的桥接模块、原生渲染管线和系统 API 调用也需要重新映射到鸿蒙的系统能力上。如果只是把 APK 丢到鸿蒙兼容层里业务代码大概率能跑起来但只要涉及相机、定位、蓝牙、推送这些与系统深度耦合的能力就会出现各种怪问题。更别说鸿蒙主推的分布式设备协同、跨端流转这些能力兼容层根本访问不到。所以想让 RN 在鸿蒙上高质量运行正路是走原生适配而不是靠 APK 兼容层碰运气。1.2 为什么 RN 团队要接鸿蒙从团队产出比来看RN 接鸿蒙的吸引力非常大。一套 JS/TS 业务代码同时覆盖 Android、iOS、鸿蒙三端这是老板最想看到的结果鸿蒙原生开发人才供给少要是每个功能都在鸿蒙侧重写一遍项目排期至少翻倍。RN 的生态本身就成熟状态管理、网络库、组件库都是现成的把鸿蒙设备当成一个新的渲染目标平台来适配比从零启动一个鸿蒙原生团队要便宜得多。也要看到目前企业侧的鸿蒙化需求确实在起来。不只是头部大厂很多做政企、教育、智能硬件、IoT 的团队也开始要求 App 支持鸿蒙设备。RN 开发者如果能在简历里写一笔“主导过 RN 鸿蒙适配”这个技能在招聘市场上是很值钱的。这篇文章不存在夸大适配难度但也不是劝退核心意思是这条路走得通而且只要你理解了桥接层后面的开发体验会越来越顺畅。1.3 三条技术路线怎么选我梳理了一下实际项目中常见的三种做法各有适用场景。方案开发成本用户体验鸿蒙原生能力适用场景纯 ArkTS 重写高按页面全部重做最好完全原生完整可深度使用分布式能力核心产品、对体验要求极高的团队React Native 鸿蒙适配层中RN 业务可复用较好接近原生通过自定义 TurboModule 扩展已有 RN 代码、需要快速覆盖鸿蒙设备的团队WebView 套壳低套网页最省事一般加载慢、交互糙弱只能通过 JSBridge 间接调用临时方案、内容型页面我最终选择的是中间这条用 OpenHarmony SIG 组维护的开源适配层让 RN 运行在鸿蒙设备上。这个适配层会把 RN 的 JS 组件渲染成 ArkUI 组件把 JS 侧的模块调用映射到鸿蒙原生能力核心组件和 API 覆盖度已经达到了可用的水平。更关键的是它允许开发者自己写鸿蒙原生模块通过 TurboModule 暴露给 JS 侧调用——这正好解决了“RN 想用鸿蒙私有能力”的刚需。2. 鸿蒙开发基础RN 开发者只需要盯住这三块2.1 ArkTS会把 TypeScript就能看懂七八成ArkTS 是鸿蒙应用开发的主力语言官方定位是 TypeScript 的超集。RN 开发者普遍有 TS 基础所以学 ArkTS 的曲线非常平缓但你得知道它比 TS 多出来的规矩。ArkTS 里常见的装饰器包括Entry、Component、State、Prop、Watch等它们会在编译期生成 UI 渲染和状态管理的逻辑。State可以类比 React 里的useState变量一变UI 自动刷新Prop就是父组件传给子组件的 propsWatch用来监听状态变化类似useEffect里对依赖项的观察。先看一个最基础的 ArkTS 页面Entry Component struct CounterPage { State count: number 0; build() { Column({ space: 16 }) { Text(当前值: ${this.count}) .fontSize(20) Button(加一) .onClick(() { this.count 1; }) } .padding(24) } }这段代码已经能看出 ArkUI 的基本形态了Column是纵向布局容器Text是文本组件Button是按钮用链式调用来设置样式和事件。重点提醒一点ArkTS 在类型检查上比 TS 严格得多any在 ArkTS 里是不被推荐的很多场景会直接编译报错。我刚开始写时习惯性地用any偷懒结果 DevEco Studio 的红线不断。这不是坏毛病反而会逼你把类型写清楚。2.2 ArkUI声明式 UI 是 React 的老熟人ArkUI 是鸿蒙的声明式 UI 框架用法和 React 的心态非常接近你描述“界面应该长什么样”框架负责在状态变化时更新它。UI 树不是写死的一堆标签而是通过build()方法动态描述。ArkUI 里没有 JSX取而代之的是build()方法加结构化组件。常见布局容器有Column纵向、Row横向、Stack层叠和List、Grid这种滚动容器。基础组件有Text、Button、Image、TextInput等。组件用链式调用来设置属性视觉上很像 Flutter 的写法Text(Hello HarmonyOS) .fontSize(28) .fontWeight(FontWeight.Bold) .fontColor(#FF6600) .margin({ top: 12 })对于 RN 开发者来说这里面没有一个概念是全新的状态驱动视图、父子组件通信、props 传递、事件回调这些在 React 里都有一套成熟心智模型。你只需要花点时间熟悉 ArkUI 的组件名和链式调用风格写起来基本没障碍。如果在 RN 里开发自定义组件的需求不复杂甚至可以理解成“用 ArkUI 写一个类似 RN 原生组件的 UI 层”。2.3 Stage 模型与 UIAbility入口和生命周期鸿蒙从 API 9 开始主推 Stage 模型。应用由一个或多个模块组成每个模块可以有多个 UIAbilityUIAbility 就像是带界面的“能力单元”承担了类似 Android Activity 的角色。一个鸿蒙应用启动后会先创建一个 UIAbility然后在onWindowStageCreate回调里把真正的页面内容加载到窗口上。RN 应用跑在鸿蒙上本质上也是在一个 UIAbility 里加载了适配层容器再由这个容器挂载 JS 引擎、渲染 React Native 视图。所以理解生命周期时机很重要如果页面还没加载完成就去初始化 RN 的 RootView或者窗口还没就绪就去请求原生权限都会遇到奇怪的时序问题。UIAbility 常见的生命周期回调有onCreate、onWindowStageCreate、onForeground、onBackground、onDestroy。可以类比酒店入住办入住是onCreate拿到房卡进房间是onWindowStageCreate入住期间离开再回来是onBackground/onForeground退房是onDestroy。RN 的页面依附于这个“房间”原生模块的初始化和清理动作也要跟着这套节奏走。3. 工程集成实操在 RN 项目里接一条鸿蒙通道3.1 环境准备与目录结构真正动手之前先把环境备齐一台可以跑鸿蒙模拟器或真机的设备最好准备真机模拟器在部分传感器能力上有差异DevEco Studio以及对应的 HarmonyOS SDKNode.js、React Native CLI 环境与 RN 版本匹配的 react-native-harmony 适配包我用的是 react-native-harmony 方案它会在 RN 工程根目录下生成一个harmony子工程。这个子工程是一个标准的 DevEco Studio 工程负责承载鸿蒙侧的入口、页面和原生模块。粗略的目录结构如下project ├── src ├── node_modules ├── harmony │ ├── entry │ │ └── src/main/ets │ │ ├── entryability │ │ ├── pages │ │ └── modules │ └── build-profile.json5 ├── package.json └── app.json这里要特别强调一个实操原则RN 版本和鸿蒙适配层的版本必须严格对齐。你如果想高版本 RN 直接配旧版适配层编译大概率会挂反过来也行不通。业界的做法是看一眼 react-native-harmony 的 release 说明确认它支持哪个 RN 版本区间再决定要不要升级自己的 RN 版本。别小看这一步很多团队在接入时第一个坑就是版本错配。3.2 桥接层JS 与 ArkTS 怎么互相喊话RN 从早期架构到现在JS 和原生之间的通信从 Bridge 演变成了 JSI 和 TurboModule。老方案是把调用序列化成消息在 JS 和原生之间传递JSI 则是直接让 JS 引擎拿到原生对象的引用性能更好、类型也更安全。鸿蒙适配层同样实现了这套机制所以你在鸿蒙上写原生模块时思路和 Android/iOS 上写 TurboModule 非常相似。把桥接层想成一条电话线JS 侧是拨号方调用方ArkTS 侧是接听方实现方如果 ArkTS 侧异步处理完再回传结果就是一次“回拨”。两边要用同一个“号码”——也就是注册名——才能对接上。侧作用关键操作ArkTS 侧实现功能注册模块TurboModuleRegistry.registerModule(模块名, factory)JS 侧获取模块调用方法TurboModuleRegistry.get (模块名)这个“模块名”必须完全一致大小写、拼写都不能差。我见过一个同事把驼峰命名的模块名写成了纯大写JS 侧取回来是null排查了半天才发现是名字对不上。3.3 权限、依赖与模块声明自定义鸿蒙原生模块如果涉及系统能力比如相机、麦克风、位置服务必须在module.json5里声明权限。声明方式和 Android 的 AndroidManifest 有些像但字段和权限名完全是鸿蒙自己的体系。拿相机权限举例大致是这么一段{ module: { name: entry, requestPermissions: [ { name: ohos.permission.CAMERA } ] } }权限声明漏掉真机运行时代码可能不会立刻崩溃但系统会静默拒绝或者弹不出授权框。这个坑在联调时很容易被忽略。另外鸿蒙侧的依赖是配在oh-package.json5里的。引入适配层相关包时版本号一定要和 RN 适配版本匹配。建议直接复制 release 文档里给好的版本组合不要自己随意升版本否则可能出现“JS 侧能编译通过鸿蒙侧一运行就崩”的诡异问题。4. 核心代码走读从 ArkTS 组件到 RN 侧调用4.1 先写一个 ArkTS 组件这里我用一个最简单的业务场景演示鸿蒙侧维护一个“问候视图”显示一段文本和一个按钮按钮点击后把事件回调给 JS 侧。先写鸿蒙侧组件Component export struct GreetingView { Prop message: string onButtonClick?: () void build() { Column({ space: 12 }) { Text(this.message) .fontSize(24) .fontWeight(FontWeight.Bold) .padding(16) Button(点我触发回调) .onClick(() { this.onButtonClick?.() }) } .padding(24) .backgroundColor(#FFF8E1) .borderRadius(16) } }这个组件完全不懂 RN它只是按鸿蒙规则写出来的普通 ArkUI 组件。Prop接收父级传入的文本按钮点击后执行onButtonClick回调。你可能会问这样一个组件怎么被 RN 用到答案是不要直接把它塞进 RN 页面而是把它封装在一个鸿蒙原生页面里再通过模块方法把数据传进去。如果你只需要在 RN 侧展示一块“鸿蒙原生 UI”更常见的做法是把 ArkUI 组件嵌入到一个 Page 里然后通过 NativeModule 刷新页面上的状态。还有一种做法是把鸿蒙组件打包成原生视图通过 RN 的 Fabric 组件接入到 JS 的视图树里。但这个复杂度更高本文先不展开先用 TurboModule 这种更直观的方式讲清楚通信链路。4.2 用 TurboModule 把能力暴露出去在鸿蒙侧写一个模块类继承 TurboModule实现业务方法然后注册到模块注册表。代码大致是这个形态import { TurboModule, Runtime, TurboModuleRegistry } from openharmony/react-native-ts-interop; import { promptAction } from kit.ArkUI; export class GreetingModule extends TurboModule { static readonly NAME GreetingNativeModule constructor(runtime: Runtime) { super(runtime) } getGreeting(name: string): string { return 你好${name} } showToast(msg: string): void { promptAction.showToast({ message: msg, duration: 2000 }) } } TurboModuleRegistry.registerModule(GreetingModule.NAME, (runtime) { return new GreetingModule(runtime) })这里每个方法都可以被 JS 直接调用它内部可以调用任何鸿蒙系统 API。比如promptAction.showToast就是鸿蒙自己的轻提示能力几乎不需要写什么胶水代码。要注意的是示例中的导入路径和父类签名可能会随适配层版本而调整但“继承基类、实现方法、注册模块”这个三步结构是稳定的。4.3 RN 侧封装并调用JS 侧的工作就很常规了。先声明模块类型再从TurboModuleRegistry取出同名模块import { TurboModuleRegistry } from react-native interface GreetingNativeModuleSpec { getGreeting(name: string): string showToast(msg: string): void } export const GreetingNativeModule TurboModuleRegistry.getGreetingNativeModuleSpec(GreetingNativeModule)调用的时候直接在业务代码里GreetingNativeModule.getGreeting(张三)就能拿到返回值。如果要更符合 React 习惯可以封装一个 Hookimport { useEffect, useState } from react export function useGreeting(name: string) { const [greeting, setGreeting] useState() useEffect(() { const result GreetingNativeModule?.getGreeting(name) setGreeting(result ?? ) }, [name]) return greeting }如果你需要鸿蒙侧主动推送事件给 JS比如页面切换、传感器数据变化、进度回调那就不能只靠同步方法要用回调或者事件发射器。最朴素的做法是在 ArkTS 侧保存 JS 传入的 callback时机到了就调用它// ArkTS 侧 private pendingCallback?: (eventName: string, data: string) void registerCallback(cb: (eventName: string, data: string) void): void { this.pendingCallback cb } notifyEvent() { this.pendingCallback?.call(nativeEvent, 来自鸿蒙侧的消息) }JS 侧传入回调时需要格外小心内存泄漏。页面销毁前一定要通知鸿蒙侧清理这个回调引用否则原生侧长期持有 JS 对象会导致内存只增不减。5. 真实项目里最容易踩的坑5.1 启动白屏为什么总是白屏“react native 启动白屏”在热搜里出现频率很高在鸿蒙适配场景下尤其常见。我在联调阶段遇到白屏的次数比过去在 Android 上加起来还多。原因其实就几类按概率排序第一JS bundle 没有正确加载。开发环境下 RN 默认从 Metro Server 拉 bundle如果手机连不上开发机的端口或者鸿蒙工程里配置的 bundle 路径不对页面就会白屏。我习惯把 bundle 打进 hap 包里避免依赖本机 server这样也方便给测试同学装包。第二RootView 挂载时机不对。适配层要在onWindowStageCreate窗口就绪之后再去加载 RN 页面如果提前挂载渲染管线没能拿到有效的窗口上下文结果就是白屏。这类问题看日志是最直接的过滤ReactNativeJS和RNOH两个关键词能看到 JS 引擎是否初始化成功、组件是否渲染完成。第三Hermes 引擎初始化失败或资源缺失。检查鸿蒙工程里是否把 Hermes 相关的 so 和资源文件正确打进去release 包最容易丢这个。排查白屏的固定流程我建议这样打开 DevEco Studio 的 Logcat过滤ReactNativeJS看 JS 层有没有报错过滤RNOH看适配层有没有抛异常确认 bundle 路径是相对的还是绝对的开发环境和 release 环境各对一遍检查 UIAbility 生命周期回调顺序必要时在onWindowStageCreate里加日志5.2 回调丢失和事件名不一致鸿蒙侧异步任务完成后要回调 JS结果页面这边毫无反应这是原生桥接开发里的通病。我遇到过的典型原因有三个。第一个是事件名或回调名不一致。RN 侧注册了一个回调叫onProgress鸿蒙侧发的事件名却是progress两边对不上自然没反应。解决办法是把事件名定义在一个共享类型文件里JS 和 ArkTS 都引用同一份常量从源头杜绝拼写差异。第二个是回调时机早于 JS 注册。原生模块刚启动页面还没把 callback 传进去鸿蒙侧就触发了事件等你注册上去事件已经错过了。处理方式是让鸿蒙侧维护一个待发事件队列等 JS 侧注册完成后再补发。第三个是不清理原生回调。JS 组件卸载后鸿蒙侧还持有旧回调不仅浪费内存还有可能把数据推到已经销毁的页面上引起崩溃。在 useEffect 的 cleanup 里调用一个cleanup()方法把鸿蒙侧的 callback 置空是标准做法。5.3 版本兼容与打包体积问题最后说版本和打包。react-native-harmony 和 RN 的版本是强绑定关系RN 升级一个 minor 版本适配层可能就要跟着换。我的建议是团队如果能统一就固定一个 RN 版本长期维护真的需要升级时先看适配层的兼容矩阵再动手。包体积方面鸿蒙 hap 包很容易做大因为 ArkTS 的依赖、RN 的 runtime、JS bundle 全在里面。release 构建时开启代码混淆不要带上 Dev 模式的 bundle 资源如果鸿蒙侧模块很多考虑拆成多个 hap 或按需加载模块避免首包无限膨胀。5.4 热搜里几个“鸿蒙”问题的快答我在查资料时也顺手翻了翻相关热词有些问题适合放在一起快速澄清。问题简要回答react native 启动白屏按 5.1 的排查流程走多数是 bundle 路径或 RootView 挂载时机问题harmonyos查看安卓版本看“设置-关于本机”里的系统版本想确认能否运行 APK要看设备是否支持对应的兼容层能力python开发鸿蒙鸿蒙原生页面开发不建议用 Python官方主推 ArkTSPython 可以用在服务端或自动化脚本侧trae 能开发鸿蒙应用吗AI 辅助编码工具可以写 ArkTS 代码但正式构建、签名、调试仍要依赖 DevEco Studio 和 HarmonyOS SDK鸿蒙应用开发高级认证想做深鸿蒙方向的可以考能帮你系统补齐知识盲区但对 RN 集成不是硬性要求这些答案都不算复杂但对刚进入鸿蒙生态的团队来说能少走很多弯路。6. 最后再分享几句真实体会我自己这几个月最大的感受是RN 接鸿蒙本质上不是“把安卓工程复制一份到鸿蒙”而是把鸿蒙当成一个一等公民平台来设计和适配。你在 JS 侧写的代码越模块化鸿蒙原生模块拆得越单一后面维护起来就越轻松。如果公司刚好有鸿蒙化要求别一开始就想着把整个 App 重写先把一个高频页面接通跑顺链路、验证稳定性再逐步推广到更多模块。还有一个小技巧我在验收阶段反复用过每次改动鸿蒙原生模块都先在 DevEco Studio 里单独跑鸿蒙侧的自测代码再回到 RN 侧联动验证。不要每次都把整条链路跑通了才检查那样出了问题很难定位到底在 JS 还是 ArkTS。开发节奏上把“鸿蒙侧方法封装一层薄薄的 ArkTS APIJS 侧只调接口不碰实现”当铁律执行两个角色各司其职配合效率会大幅提升。这个过程确实绕不开踩坑但每踩一个坑你对鸿蒙这套系统的理解就会深一层。等哪天你也能随手写一个自定义鸿蒙组件丢给 RN 同事调用那才算真正入门了。