很多人第一次听到“在React Native中开发鸿组件”这个需求时，通常会先愣一下：RN不是做跨平台App的吗，鸿蒙不是一套独立的系统吗，这两者怎么凑到一起？我最初也抱着同样的疑问去做技术预研，最后发现“RN跑在鸿蒙上”不仅可行，而且已经有一套相当成熟的工程链路。这套链路的核心就在于，将鸿蒙OS的原生组件与原生能力，通过桥接层暴露给React Native的JS运行时，让一套业务代码既能跑在iOS/Android，又能跑在鸿蒙设备上，并且还能直接调用鸿蒙系统独有的分布式能力。
标题里的“鸿组件”，严格来说指的是HarmonyOS原生组件。开发鸿组件的过程，其实就是理解鸿蒙原生开发范式、再把RN的调用协议翻译成鸿蒙侧实现的过程。这篇文章会从鸿蒙开发的基础知识讲起，接着拆解集成方案和桥接原理，最后给出一套可以直接抄的Demo流程，以及我踩过的坑。适合三类读者：RN端工程师、鸿蒙端工程师、跨端技术负责人。如果你是纯前端背景，后面涉及ArkTS或Stage模型的段落可以先扫一眼，不影响理解主线。
1. 为什么要在React Native里接鸿蒙：跨端摊薄成本
1.1 鸿蒙生态的现状与角色
最近两年，鸿蒙OS（HarmonyOS）在终端市场的存在感越来越强，从一个手机操作系统逐步扩展成覆盖手机、平板、车机、智能家居、办公设备的全场景操作系统。对业务团队来说，这意味着原先只需要考虑iOS和Android两端，现在可能要面对第三类设备集群。鸿蒙的设计核心是“分布式”，不同物理设备之间可以像同一个系统内的模块一样协同工作，这听起来很美好，但也给应用开发带来了一个新的现实问题：要不要为鸿蒙单独维护一套原生工程？
如果答案是肯定的，那么一个功能就要写三套UI、三套逻辑、三套发布流程，人力成本直接翻倍。如果答案是否定的，又不知道怎么把现有技术栈平滑迁移过去。这正是React Native这类跨端框架在鸿蒙生态里重新被关注的原因。跨端框架的价值从来不是“消灭原生”，而是把业务代码从操作系统里抽象出来，让原生只负责系统能力和性能敏感的模块。
1.2 RN接入鸿蒙的真实场景
我梳理了几个自己接触过的真实项目，RN接入鸿蒙的需求大致分成三类：
一是存量RN应用需要快速覆盖鸿蒙。团队已经用RN做了很多业务页面，现在要求App能在鸿蒙设备上跑起来。这种情况下最理想的状态是“改配置不改业务代码”，RN桥接层几乎是唯一能兼顾成本和体验的路径。
二是超级App内的动态化需求。主工程是鸿蒙原生开发的，但部分运营页面需要频繁更新，不想每次都走应用发版流程。此时RN作为动态化容器嵌入鸿蒙主工程，RN页面负责更新频繁的业务，鸿蒙原生侧负责账号、支付、推送等基础能力，两边通过桥接互相调用。
三是业务本身需要用到鸿蒙独有的分布式能力。比如跨设备文件流转、多设备协同操作、分布式数据库同步。这些能力在纯Web技术栈里拿不到，必须在鸿蒙原生侧通过特定API调用，然后再封装给RN层使用。这种诉求往往是决定“要不要为鸿蒙单独开发原生模块”的最终理由。
1.3 为什么不选其他方案
在决定用RN桥接之前，我还对比过另外两条路线，各有各的适用场景，但都不适合大多数团队。
WebView壳方案开发成本最低，把H5页面包一层原生壳，很快就能在鸿蒙设备上跑起来。但H5在交互流畅度、系统能力调用、离线和弱网表现上都有明显短板，只适合低频展示类页面，扛不住核心业务。
鸿蒙原生重写方案体验最好，系统能力调用没有任何阻碍，但成本也是最高的。如果把现有RN页面全部用ArkTS重写一遍，等于把跨端节约的人力又还了回去，而且后续双端并行维护的负担很重。
RN桥接方案正好取中间值。JS业务代码仍然跑在RN环境中，底层原生UI和模块用鸿蒙的ArkTS实现，通过桥接协议与JS通信。开发成本中等，体验接近原生，系统能力调用完整。三种方案对比如下：
| 方案 | 开发成本 | 体验一致性 | 系统能力 | 适用场景 |
|---|---|---|---|---|
| WebView壳 | 低 | 一般 | 弱 | 低频H5复用 |
| 鸿蒙原生重写 | 高 | 高 | 强 | 关键系统应用 |
| RN桥接 | 中 | 高 | 强 | 跨端业务复用 |
桥接方案的核心价值，是把RN的跨端能力和鸿蒙的系统能力做叠加，而不是替代其中任何一方。
2. 动手前必须知道的鸿蒙开发基础
2.1 鸿蒙的系统架构认知
做鸿组件开发，不需要把整份系统架构文档读完，但有几个关键概念必须建立起来，否则后面连代码该写在哪个文件里都找不到。
鸿蒙OS的整体结构大致分为内核层、系统服务层、框架层和应用层。内核层提供基础调度能力，但对应用开发者来说接触最多的其实是框架层，它提供了UI框架、Ability框架、分布式数据管理等一系列开发接口。和Android不同，鸿蒙应用的基本运行单元是Ability而不是Activity。一个应用通常由一个或多个UIAbility组成，每个UIAbility对应一个可独立启动和关闭的窗口单元。
分布式软总线是鸿蒙区别于其他系统最核心的设计之一。它让多个物理设备在系统层面被抽象成一个逻辑整体，文件、数据、任务可以在设备之间流转。这意味着RN桥接层未来如果要调用这些分布式能力，并不是通过什么魔法，而是通过鸿蒙原生侧提供的分布式API，然后把结果转换回标准的数据结构传给JS层。理解这一点，后面写模块时就不会走偏。
2.2 开发范式：ArkTS、ArkUI、Stage模型
鸿蒙应用开发现在的标准范式是“Stage模型 + ArkTS + ArkUI”。ArkTS是TypeScript的超集，在纯TS语法基础上增加了UI描述能力，最重要的一点是引入了装饰器语法来声明组件、状态、入口。ArkUI则是一套声明式UI框架，写法上有点接近Flutter或SwiftUI的体验。
一个最简单的鸿蒙页面长这样：
@Entry @Component struct Index { @State message: string = 'Hello HarmonyOS'; build() { Column() { Text(this.message) .fontSize(20) .fontWeight(FontWeight.Bold) } .width('100%') .height('100%') } }@Entry标记页面入口，@Component标记这是一个组件结构，@State标记状态变量，状态变了UI自动刷新。这种声明式思想RN开发者应该很熟悉，因为React本身就是声明式范式，只是鸿蒙用装饰器把声明式表达得更显式。
Stage模型解决的是应用生命周期问题。UIAbility的创建、可见、前后台切换、销毁都由系统管理，开发者需要在特定回调里执行自己的逻辑。做RN桥接时，RN实例的初始化、启动、销毁都要挂在这些回调上，这块后面单独讲。
2.3 鸿蒙组件与RN组件的对应关系
把鸿蒙组件接入RN，本质上是解决两个系统之间的“相互理解”问题。RN侧认识的是React组件树，鸿蒙侧认识的是ArkUI组件树，两侧各自运行、各自维护，桥接层负责翻译。
在鸿蒙侧，自定义原生组件通过ComponentBuilder接口生成，每个组件有一个唯一的字符串标签，例如RNCustomBanner。在RN侧，JS代码通过requireNativeComponent或codegenNativeComponent把同一个标签注册成React组件。这样当RN渲染这个组件时，桥接层会找到对应的鸿蒙原生组件，把它挂载到页面节点上。原生模块同理，鸿蒙侧实现TurboModule接口，RN侧通过NativeModules直接调用。
我习惯把这种映射关系理解成一个“通讯录”：桥接层维护一张注册表，每个RN组件或模块名称对应一个鸿蒙侧实现，两侧用同一个名字找到对方。名字对不上，任何数据都传不通。
2.4 环境准备：一套完整的工具链
开始写代码前，先把工具链准备好。常用的版本组合我整理在下面，虽然不是唯一答案，但至少能保证少踩一些版本坑：
| 工具/组件 | 建议版本 | 说明 |
|---|---|---|
| DevEco Studio | 5.x及以上 | 鸿蒙原生IDE，内置模拟器 |
| HarmonyOS SDK | API 12以上 | 建议跟随IDE默认版本 |
| React Native | 0.73左右 | 过老的RN版本可能没有对应适配包 |
| 社区桥接包 | 与RN版本对应 | 不同RN版本要匹配合适的适配包 |
| Node.js | 18 LTS以上 | Metro打包依赖 |
| 真机或模拟器 | API 12+ | 模拟器调试速度更快 |
这里的版本匹配是最容易踩坑的地方。社区适配包对RN版本和HarmonyOS API版本都有明确的对应关系，安装之前先去它的发布页或文档里确认一下“当前版本支持哪些RN版本、支持哪些HarmonyOS API”，不要盲目拉最新版。我见过不少项目浪费大量时间在编译失败上，最后发现只是版本不匹配。
3. RN集成鸿蒙的整体架构思路
3.1 三条集成路线与桥接方案的定位
工程层面，RN集成鸿蒙有三种可选路线，适用范围各不相同。
第一种是“WebView页中页”，即在鸿蒙原生工程里用Web组件加载某个H5地址或离线包。这种方案没有真正接入RN，只是把H5包在一个原生容器里，开发成本最低，但RN生态的资源都用不上，性能也受限于WebView。
第二种是“RN独立页面”，就是鸿蒙原生App里，某些页面完全由RN渲染。主工程创建好一个窗口后，在该窗口上启动RN运行时，由RN来接管整个页面的UI。这是比较常见的混合开发模式，适合信息流、运营活动页、表单页这类动态化要求高的页面。
第三种是“RN全应用”，整个App从启动页到内部页面全部用RN实现，鸿蒙原生层只提供系统能力桥接。这种模式适合从零起步、业务高度跨端的项目。
从工程实现上讲，后两种模式本质上相同，都需要在鸿蒙侧初始化RN运行时，并注册对应的原生模块和组件。区别只在于页面由谁主导。我的建议是初期先用“RN独立页面”验证链路，跑通后再决定要不要扩大RN的覆盖范围。
3.2 桥接层设计：模块、组件、事件
桥接层是RN与鸿蒙的翻译官。它主要负责三件事：模块方法调用、组件渲染、事件回调。
模块方法调用解决“JS需要调用鸿蒙原生能力”的问题。鸿蒙侧实现一个TurboModule的子类，JS侧通过NativeModules直接调用。参数可以是基本类型、对象、数组，返回值可以是同步的普通值，也可以是异步的Promise。这里要注意，鸿蒙侧的桥接层并不建议在主线程里做耗时操作，IO、网络、复杂计算都应该放到异步任务里，最后把结果回调给JS。
组件渲染解决“RN页面里需要嵌入鸿蒙的复杂原生UI”的问题。比如鸿蒙系统对某些复杂列表或视频播放有专门的组件实现，这些组件无法直接用RN基础组件替代，就需要通过ComponentBuilder封装成自定义原生组件。RN合成器在创建该组件时，桥接层会调用鸿蒙侧的Builder方法生成对应的原生组件实例。
事件回调解决“鸿蒙侧主动通知JS”的问题。例如用户点击了原生轮播组件中的一张图片，点击事件发生在鸿蒙侧，必须通过事件机制传给RN的JS层，JS层才能更新页面状态或触发跳转。
这三个方向就是整个桥接层的主干，后面所有代码都会围绕这三件事展开。
3.3 工程结构规划
一个RN+鸿蒙的工程，从目录结构上就要把两侧职责分开，避免代码越写越乱。比较清晰的规划是：
entry/ src/main/ ets/ entryability/ // Stage模型入口 pages/ // 鸿蒙原生页面 rn/ modules/ // 原生模块实现 components/ // 原生组件Builder Registry.ts // 注册中心 resources/ // 鸿蒙侧资源 build-profile.json5 module.json5 js/ src/ pages/ // RN业务页面 components/ // RN公共组件 native/ DeviceInfo.ts // 原生模块类型声明鸿蒙工程管壳子、系统能力和原生模块，RN工程管跨端业务。所有的桥接协议文件建议单独放一个目录，后续加新模块的时候，只需要在鸿蒙侧新增一个Module文件、在Registry里注册一行，再在RN侧声明一下类型，就能完成一次扩展。
3.4 选型建议与判断标准
团队在做技术决策时，我建议先回答三个问题。
第一个问题是“现有代码能不能复用”。如果业务代码高度依赖RN生态的库和组件，那桥接方案的优势就很明显；如果业务本来就很薄，原生重写反倒更清晰。
第二个问题是“系统能力依赖有多深”。如果App的核心功能全部建立在鸿蒙独有的分布式能力上，RN桥接只能减少UI层的工作量，原生模块开发的比重依然很大，这时要评估好工作量。
第三个问题是“团队具备哪种技术栈”。一个团队里至少要有一个熟悉RN的人和一个熟悉鸿蒙原生的人，缺一不可。单纯只有RN工程师，碰到原生模块疑难问题会卡很久；单纯只有鸿蒙工程师，JS侧性能优化和RN生态问题又无人接得住。
4. 实操：从零搭建RN调用鸿蒙能力的Demo
4.1 初始化工程与依赖配置
先创建一个鸿蒙原生工程，工程名可以随便取，比如HarmonyRNBridge。用DevEco Studio完成初始化后，打开oh-package.json5，添加社区桥接包的依赖。代码示例以@rnoh/react-native-openharmony为例，实际包名和应用配置以你选择的适配包文档为准。
{ "dependencies": { "@rnoh/react-native-openharmony": "file:./react-native-harmony", "react-native": "file:../node_modules/react-native" } }这里有个细节：RN代码本身仍然在Node环境中管理，所以工程根目录还会有一个package.json和node_modules。创建好后，在鸿蒙工程目录里执行安装命令，让DevEco能识别到RN的依赖包。
接着处理module.json5中的Ability配置，把默认入口替换成RN桥接包提供的Ability，或者在现有UIAbility的启动回调中手动初始化RN运行时。二选一即可，新手建议直接用桥接包自带的Ability入口，省去手动初始化的工作。
4.2 创建鸿蒙原生模块：设备信息模块
第一个Demo模块我选择“设备信息”，因为它不依赖UI，返回数据简单，最适合验证链路。在鸿蒙侧新建一个DeviceInfoModule.ts，继承适配包提供的TurboModule基类。
import { TurboModule, TurboModuleContext } from '@rnoh/react-native-openharmony'; import { deviceInfo } from '@ohos.deviceInfo'; export class DeviceInfoModule extends TurboModule { constructor(ctx: TurboModuleContext) { super(ctx); } getDeviceName(): string { return deviceInfo.name; } getApiVersion(): number { return deviceInfo.sdkApiVersion; } getDeviceType(): string { return deviceInfo.deviceType; } }方法写好后，需要把这个模块注册到桥接层。找到注册中心文件，在模块列表里加一行映射：
this.ctx.rnInstance.registerTurboModule( 'DeviceInfo', () => new DeviceInfoModule(this.ctx) );注意这里的模块名DeviceInfo是JS侧将来调用的名字，建议统一用驼峰命名，不要和已有模块重名。注册顺序也很重要，必须在RN实例启动之前完成注册，否则JS侧调用时会拿到undefined。
4.3 JS侧调用与类型声明
RN侧代码现在就可以直接调用这个模块了。在RN项目的任意业务文件里：
import { NativeModules } from 'react-native'; const { DeviceInfo } = NativeModules; const deviceName = DeviceInfo.getDeviceName(); const apiVersion = DeviceInfo.getApiVersion();为了开发体验好一点，建议在RN侧单独建一个类型声明文件，把原生模块的方法签名定义清楚，这样编辑器里会有完整的类型提示。
declare module 'react-native' { interface NativeModulesStatic { DeviceInfo: { getDeviceName(): string; getApiVersion(): number; getDeviceType(): string; }; } }这一步不是必须的，但对工程长期维护帮助很大。原生模块多了以后，没有类型声明很容易把参数传错。
4.4 封装一个鸿蒙自定义UI组件
模块调用通了，接下来验证自定义UI组件。这里以一个最简单的“原生色块组件”为例：鸿蒙侧提供一个纯色背景的组件，RN侧可以传颜色值进去，点击时把颜色值回调给JS。
鸿蒙侧需要定义一个继承自元组件的组件类，并通过ComponentBuilder暴露给桥接层：
import { ComponentBuilder, CustomComponent, RenderNode } from '@rnoh/react-native-openharmony'; export class NativeColorBlock extends CustomComponent { private color: string = '#FF0000'; onReceiveCommand(command: string, args: any[]) { if (command === 'select') { this.onSelectColor(); } } private onSelectColor() { // 将点击事件回传给RN侧 this.emit('onColorSelected', { color: this.color }); } } export const NativeColorBlockBuilder: ComponentBuilder<NativeColorBlock> = (ctx, tag) => new NativeColorBlock(ctx, tag);然后在注册中心把这个组件接入：
this.ctx.rnInstance.componentRegistry.registerComponent( 'NativeColorBlock', NativeColorBlockBuilder );RN侧通过requireNativeComponent注册并调用：
import { requireNativeComponent } from 'react-native'; const NativeColorBlock = requireNativeComponent('NativeColorBlock'); export function RNNativeColorBlock(props: { color: string; onColorSelected?: (event) => void }) { return <NativeColorBlock {...props} />; }这样RN页面就能直接使用这个原生组件了。写自定义组件时最容易犯的错是忘记把组件注册进注册中心，结果RN合成器渲染时找不到对应的原生实现，直接报错或白屏。
4.5 启动与连通性验证
所有代码写完后，验证链路的操作顺序很关键。我习惯先启动Metro，再启动鸿蒙工程：
npm start然后在DevEco Studio里选择模拟器，运行鸿蒙工程。App启动后，RN业务代码会从Metro加载，页面渲染完成后可以在鸿蒙侧日志中过滤关键词ReactNative，看到实例初始化相关的输出。如果设备信息模块能正常返回数据，说明模块层通路没问题；如果自定义组件能显示并响应点击，说明组件层通路也没问题。
首次跑通这个Demo可能花上大半天时间，中间大概率会碰到几个坑，但链路一旦跑通，后面加新模块就是照葫芦画瓢，会顺利很多。
5. 关键细节与参数说明
5.1 生命周期对接
鸿蒙侧维护RN实例，最忌讳的做法是把RN实例当成一个单纯页面来管理。UIAbility的onCreate阶段就应该完成RN运行时的初始化，onWindowStageCreate阶段再创建窗口并挂载RN页面。
页面进入后台时，对应的RN实例应该暂停JS定时器和动画；回到前台时恢复。这些监听操作要通过UIAbility的onForeground和onBackground回调转发给RN运行时。App退出时，onDestroy里要调用RN实例的销毁方法，释放JS引擎和原生资源。
这块做得不仔细，会出现一种很隐蔽的问题：页面切换后内存就涨一次，多切几次直接卡死。本质就是RN实例没有跟随Ability生命周期正确释放。
5.2 线程模型与耗时操作
RN的架构里天然存在多个线程：JS线程负责业务逻辑，原生UI线程负责渲染，原生模块线程负责处理系统调用。鸿蒙侧的桥接层同样要遵守这套规则。
原生模块的方法默认运行在哪个线程，取决于适配层的实现。但无论默认在哪，耗时操作都不应该阻塞UI线程。比如读取分布式文件、查询系统信息、网络请求，都应该放进异步任务。
开发时可以在鸿蒙侧这样处理耗时逻辑：
getDeviceInfo(): Promise<DeviceInfoData> { return new Promise((resolve) => { // 放到异步任务里执行 setTimeout(() => { const data = this.collectDeviceInfo(); resolve(data); }, 0); }); }JS侧调用时用await接收Promise结果，这样不会卡住页面渲染。这也是为什么原生模块的方法签名最好设计成返回Promise而不是同步返回值，同步返回值虽然简单，但在复杂业务里很容易放大性能问题。
5.3 事件传递与数据格式限制
鸿蒙侧主动向JS侧发事件，有几种不同的通道。最常用的是在原生组件上通过emit方法发送，JS侧监听组件实例上的对应事件。另一种是定义全局事件发射器，让多个页面都能收到。
无论哪种方式，事件里的数据都必须是可序列化的普通对象。传入复杂对象、类实例、函数都会被截断或直接转换失败。这个限制看起来基础，实际开发中总有新人试图把某个原生客户端对象直接传给JS，最后拿到一个看不懂的异常。
事件命名建议统一加前缀，例如onColorSelected、onBannerClick，避免和RN内置事件冲突，也方便排查问题。
5.4 资源与图片加载
RN页面里的图片资源分为两类：一类由Metro打包进JS bundle，另一类是鸿蒙原生资源目录中的图片。前者通过Image组件正常引用即可，但如果在自定义原生组件里需要显示一张图片，就不能直接传二进制数据。
正确做法是把图片路径转换成标准URI，鸿蒙侧用Image组件加载。RN侧可以使用resolveAssetSource获得资源的具体信息，然后传给原生组件。鸿蒙侧在处理时要对本地路径和网络路径做区分，本地文件优先走文件读取，网络图片则交给图片加载库。
字体和图标资源也要提前规划。RN默认使用系统字体，如果页面设计稿要求特定字体，需要把字体文件同时放到鸿蒙资源目录中，并在桥接层暴露字体注册方法，由RN侧按需注册。否则会出现在iOS和Android上都显示正常，到鸿蒙上字体却变成默认体的问题。
6. 常见问题与排查技巧实录
6.1 RN工程构建失败，提示找不到入口
现象：鸿蒙工程编译通过，但启动App直接闪退，日志里提示Unable to load script或找不到RN页面入口。
排查顺序：先确认Metro是否启动，再看鸿蒙工程的资源目录里有没有打包好的jsbundle文件。开发阶段通常依赖Metro实时加载，真机调试时要检查Dev Server地址是否可达；发布阶段则必须把bundle打包进工程，否则离线环境下无法启动。
解决：开发阶段保持Metro运行，模拟器里通过localhost:8081访问；真机或发布环境用react-native bundle生成离线bundle，放到鸿蒙工程的rawfile目录下，并配置正确的加载路径。
6.2 原生模块在JS侧拿到undefined
现象：代码里写了NativeModules.DeviceInfo，运行后却拿到undefined。
原因几乎都出在注册环节：要么没有调用registerTurboModule，要么注册时模块名拼写不一致，要么注册时序晚于RN实例启动。另一个容易被忽略的原因是模块代码里抛了异常，适配层捕获后静默跳过注册。
排查技巧：启动时在鸿蒙侧日志里过滤registerTurboModule关键词，能看到当前已注册的所有模块名。JS侧可以先打印Object.keys(NativeModules)，把两份列表对照一下，名字对不上或缺失一目了然。
6.3 自定义组件白屏或不渲染
现象：RN页面能渲染，但某个自定义原生组件区域是空白。
先检查注册表里组件名是否一致。然后检查组件尺寸，鸿蒙自定义组件如果没有明确的宽高约束，可能被测量为零大小，看起来就像没有渲染。解决方法是动态测量容器尺寸，或通过props传入固定宽高。
还有一个坑是属性名映射。鸿蒙侧接收的props属性名必须和RN传入的名称严格一致，大小写不能错。RN里写backgroundColor，鸿蒙侧通过this.props.backgroundColor获取，如果鸿蒙侧写成了background-color，数据就会丢失，组件也渲染异常。
6.4 打包后资源缺失
发布阶段最常遇到的坑是图片资源和字体缺失。开发阶段Metro会把所有资源打包好，编译发布时如果资源路径没有全部同步到鸿蒙工程，就会出现图片空白、字体退化。
解决思路是把RN工程的所有静态资源当作发布产物的一部分，用脚本统一拷贝到鸿蒙工程的资源目录，并在构建流程里加入校验，资源文件数量对不上就中止构建。不要指望手工同步，任何手工步骤都可能在版本迭代中被遗漏。
6.5 性能与内存问题
RN桥接方案最容易被诟病的地方是启动速度和内存占用。常见原因有两个：RN实例创建过重，以及原生组件与JS频繁通信。
RN实例初始化本身有固定开销，解决思路是尽量复用实例，不要每个RN页面都创建一套新引擎。如果项目是“鸿蒙原生+RN页面”的混合模式，可以考虑维护一个全局唯一的RN运行时，页面切换时只销毁当前视图，不销毁实例。
原生组件和JS之间通信也不要过于频繁。比如每帧都传数据，或者每次滑动都回调事件，都会造成性能瓶颈。规避办法是数据聚合，把批量数据合并成一次回调，或者原生侧先做计算，只把结果传给JS。
| 问题 | 常见原因 | 排查/解决办法 |
|---|---|---|
| 启动闪退 | Metro未启动或bundle缺失 | 启动Metro，检查资源打包 |
| NativeModules字段undefined | 模块注册缺失/时序错误 | 过滤日志核对注册表 |
| 组件白屏 | 注册名不一致/尺寸为零 | 核对标签名，设置宽高 |
| 图片加载失败 | 资源未同步到鸿蒙目录 | 脚本同步静态资源 |
| 页面切换内存上涨 | RN实例未正确释放 | 复用实例，跟随生命周期销毁 |
7. 写在最后：这些经验值得你复制
我实际把RN接入鸿蒙这个方案从预研推到上线之后，最大的体会是“桥接层决定了项目的天花板”。业务页面写得再漂亮，桥接层设计得混乱，后面加模块、排查问题都会很难受。所以如果团队刚起步，我建议先花时间把模块注册、组件注册、事件回调这三条基础通道设计清楚，再铺业务代码。
另一个实际教训是，做这类跨端集成项目，团队里至少要有一个能看懂鸿蒙侧日志的人。很多问题表面上出在RN侧，根子其实在原生侧。两边日志贯通之后，很多疑难问题都能快速定位。建议在开发环境里把鸿蒙侧注册和日志输出做成默认开启，发布时再关掉。
最后分享一个小技巧：如果你刚开始接触这个方向，不要一上来就铺复杂业务组件，先做一个“设备信息模块 + 一个色块组件”的最小Demo，把链路跑通。这个Demo看起来不起眼，但能帮你把所有概念串起来，后面再接触分布式能力调用就会发现，它们和读取一个设备信息本质上没有区别，都是“鸿蒙原生侧实现能力，桥接层注册暴露，JS侧按协议调用”。跨端开发这件事，最大的门槛永远在最开始那段链路里。
