最近我身边好几个做 React Native 的同行都在聊“鸿蒙开发激励”这件事。有的公司给鸿蒙方向单开了预算有的团队把鸿蒙适配列进了今年的硬指标招聘软件上“鸿蒙开发工程师”的岗位也明显多了起来。我们小组年初开了几次会最终定下一个方向现有 RN 代码不推倒重写但要尽快跑通“React Native 代码在 HarmonyOS 上跑起来”这条链路。真正动手之后才发现标题里那句“在 React Native 中开发鸿组件鸿蒙组件”背后要解决的事情比想象中多得多。首先得补鸿蒙开发的基础认知比如 ArkTS、ArkUI、Stage 模型这些和安卓完全不同的概念其次要解决 RN 工程与鸿蒙应用的集成问题这涉及到工具链、构建方式、原生模块桥接最后才是把一个个业务组件真正封装成可复用的鸿组件。这篇文章就是把整套过程里我想明白的东西和踩过的坑记录下来给同样在评估 RN 加鸿蒙这条路的同学一个参考。1. 基础是关键先把鸿蒙OS的地基摸清楚1.1 鸿蒙OS不是安卓换皮架构层面到底换了什么先说一个很多人容易踩的认知误区。早期 HarmonyOS 兼容安卓 APK于是不少开发者默认“鸿蒙就是安卓换皮把我的 RN 工程打包成 APK 能装上去就能直接跑”。这个认知在 HarmonyOS NEXT 这一代是要出事的——NEXT 已经去掉了 AOSP 兼容层APK 装不了以前安卓那种“写一次到处跑”的惯性思维直接失效。从开发层面看鸿蒙和安卓几乎每个环节都不一样。语言从 Java/Kotlin 变成了 ArkTSUI 框架从 View/XML 变成了 ArkUI 声明式写法应用模型从安卓四大组件变成了 Ability 组件模型构建工具从 Gradle 换成了 hvigor包管理从 Maven 换成了 ohpm。工程结构、签名机制、资源目录、权限模型也各有各的规矩。我列了一个对比表方便从安卓转过来的同学快速建立坐标系维度Android 传统开发HarmonyOS NEXT 开发开发语言Java / KotlinArkTSTS 子集加严格约束UI 框架View XML 布局ArkUI 声明式组件模型应用入口Activity / Service 等四大组件UIAbility / ExtensionAbility构建工具Gradlehvigor包管理Maven / Gradle 依赖ohpm安装包APKHAP运行环境ART 虚拟机ArkCompiler 运行时跨设备能力弱需自行实现分布式软总线原生支持看完这张表应该能明白一件事鸿蒙不是安卓的更新版是另一套独立系统。RN 团队做适配时最忌讳的就是拿安卓项目里的那套配置和经验硬套。踏踏实实把鸿蒙的开发范式重新学一遍后面反而更顺利。1.2 “分布式”三个字落到开发上意味着什么鸿蒙OS 对外最常提的是“分布式操作系统”这个概念的份量比宣传语要重。传统手机系统是以单设备为中心应用跑在手机上数据和任务都跟着手机走。鸿蒙的底层设计则是以“多设备协同”为中心设备之间通过分布式软总线进行通信发现、组网、传输都不需要路由器中转手机、平板、智慧屏、手表可以拧成一个逻辑上的“超级终端”。对做 RN 桥接的开发者来说分布式最直接的影响是你在鸿蒙侧封装组件时能力边界不再局限于一台设备。比如一个跨设备文件传输组件、一个分布式数据同步组件、一个任务流转组件这些都是鸿蒙侧原生的系统能力可以通过桥接层暴露给 JS 侧调用。这意味着什么意味着设计鸿组件时API 的输入输出不能只想着“本机数据”。举例来说跨端同步一份笔记内容组件要考虑远端设备不在线时的状态反馈、同步冲突如何处理、页面在流转过程中生命周期怎么保存。这些在传统 RN 组件里很少碰到但是在鸿蒙场景下是核心体验的一部分。如果只是把原来的网络请求组件搬过去等于浪费了鸿蒙最大的差异化优势。1.3 ArkTS极其严格TS的野路子先收一收要说鸿蒙开发基础里对 RN 团队“杀伤力”最大的一点我首推 ArkTS 的约束性。ArkTS 在 TypeScript 基础上做了一套更严格的限制目的是让代码可以静态分析、让方舟编译器做深度优化。但副作用就是TS 里很多“自由世界”的写法在 ArkTS 里直接编译不过。具体踩坑包括不推荐或不允许使用any类型不支持解构赋值至少某些场景下受限不允许动态给对象/类添加属性对Object字面量的写法有额外要求部分泛型边界也有自己的一套规则。前端和 RN 开发者写惯了 TS 的各种 trick跑到 ArkTS 里会发现一大批第三方库过不了编译。这个约束对 RN 集成的影响是真实的。RN 生态里大量 npm 包都是常规 TS 写法部分包在鸿蒙侧直接编译会报错。我们当时的应对策略是把所有原生模块的 JS 侧接口统一收敛到一个封装层封装层内部做类型清理对外暴露的接口尽量是简单的string、number、PromiseT避免把第三方包的类型系统直接铺到 ArkTS 边缘。代价是多写一层胶水代码但换来的是整个工程的稳定性。所谓“鸿组件”鸿蒙组件其实就是在这个封装层之上沉淀出来的产物JS 侧提供稳定的 React 组件接口鸿蒙侧通过 rnoh 的模块注册机制把原生能力注册进去两边各司其职。开发它的前提就是上面这套鸿蒙基础认知得先立住。2. 架构决定接入方式RN为什么能跑在鸿蒙上2.1 先搞清楚RN的“三层模型”与新架构要理解 RN 在鸿蒙上怎么跑得先知道 RN 本身是怎么组织的。经典架构下RN 内部有三条业务链路JS 线程负责运行业务逻辑Shadow 线程负责计算虚拟节点树和布局UI 线程负责真正渲染。JS 侧和原生侧之间靠 Bridge 通信Bridge 会把调用序列化后批量发送效率不高而且数据类型要能 JSON 序列化。新架构Fabric TurboModule JSI重点解决了两件事。第一件JSI 取代了 BridgeJS 对象和 C 对象之间可以互操作不再需要全量序列化。第二件Shadow 树移到了 C 层统一管理渲染管线更清晰。也就是说新架构下 RN 的核心引擎本身是跨平台的 C 实现真正依赖平台的只有线程绑定、UI 渲染接口和原生模块的实现细节。这也是 RN 能在鸿蒙上落地的架构基础。只要把平台相关的那部分换成鸿蒙能力C 核心不动JS 业务代码几乎原样保留RN 就能跑起来。2.2 rnoh做了什么事社区主导的 rnohReact Native OpenHarmony项目干的就是这件“换平台实现”的事。它通过 N-APINode-API把 RN 的 C 核心接到鸿蒙的运行时上渲染层走 ArkUI 的组件树原生模块走鸿蒙侧的 TurboModule 实现。简单说rnoh 做的事情可以理解为三层JS 业务代码照常写 React 组件、Hooks、状态管理这部分完全复用。RN 的引擎核心C 部分通过鸿蒙提供的 N-API 运行起来。RN 的 View/Text/Image 等基础组件映射到 ArkUI 对应的原生组件布局计算出来后渲染到 ArkUI 的树里。这条技术路线的好处很清楚RN 团队不需要自己包一层鸿蒙 WebView不需要把业务代码重写成 ArkTS也不需要维护两套 UI。组件映射、模块桥接这些脏活由 rnoh 承担业务层改动被压到最小。实际体验下来RN 的 JS 侧能调用的基础组件和模块基本都能用第三方组件库则需要看是否适配了鸿蒙。2.3 版本对应关系先锁死不然装完就报错RN 上鸿蒙最让人头大的不是架构是版本矩阵。RN 版本、rnoh 版本、DevEco Studio 版本、HarmonyOS SDK 版本、hvigor 版本、Node 版本、JDK 版本七个变量互相咬合。任何一个对不上安装依赖或编译时就会冒出各种莫名其妙的报错。我的建议是动手之前先定死“三件套”。RN 版本锁死你当前项目用的版本不要顺手升级。rnoh 版本选择与该 RN 版本匹配的 rnoh 版本以官方 Release Note 为准。HarmonyOS API 版本对应 DevEco Studio 里的 SDK 版本。原因在于rnoh 的适配工作是跟着 RN 版本走的比如某个 rnoh 版本针对 RN 0.72、另一个针对 0.73用错组合就会出现模块找不到、组件注册失败、编译期符号缺失等一系列问题。我们第一次接入时没锁版本照着旧文档硬配结果构建链全线报错排查了两天最后发现就是版本错位。所以这一步别嫌麻烦先看官方文档的版本对应表再动手。3. 实操把RN工程接进鸿蒙的完整步骤3.1 准备工具链DevEco Studio、签名与真机在真正写代码之前先把环境准备好。安装 DevEco Studio装好后在 SDK Manager 里拉取对应版本的 HarmonyOS SDK。配置 Node.js 和 JDK版本要求按 DevEco Studio 官方说明来。准备一台 HarmonyOS NEXT 真机或者用 DevEco 自带的模拟器。注册华为开发者账号申请调试证书和 Profile这个环节是必做的没有签名配置HAP 装不到真机上。签名这步容易掉坑。安卓开发时 debug 签名通常是自动生成的鸿蒙侧则要手动配置。需要在 AppGallery Connect 里创建项目生成证书和 Profile然后把证书文件下载到本地之后在工程的build-profile.json5里指定签名信息。我们团队第一次弄的时候在证书类型、包名、Profile 的绑定关系上卡了一天。建议仔细看官方文档的“应用签名”章节把包名从头到尾统一避免改来改去。3.2 生成鸿蒙壳工程与核心配置当环境就绪后这才是真正的集成起点。rnoh 提供了 CLI 工具可以从现有 RN 项目生成一份鸿蒙壳工程。实际操作中我的流程大致如下# 先安装 rnoh 核心库 npm install rnoh/react-native-harmony # 使用 CLI 生成鸿蒙工程 npx react-native-harmony-cli --output harmony执行后项目根目录下会多出一个harmony文件夹。里面能看到AppScope/、entry/、build-profile.json5、oh-package.json5、hvigorfile.ts这些鸿蒙特有文件。接下来要做的配置有三个重点。第一把鸿蒙应用包名和签名信息配置到build-profile.json5的signingConfigs里。这里需要填证书文件路径、Profile 路径和密码具体字段名以当前 DevEco Studio 版本为准。第二在entry/src/main/module.json5里确认 UIAbility 的配置文件。默认生成的壳工程已经包含页面入口逻辑RN 业务会加载到这个 Ability 中。第三把 RN 的 JS Bundle 打包到鸿蒙侧的 assets 目录。可以在 RN 工程里加一条打包脚本把 bundle 打进entry/src/main/resources/rawfile/下这样 App 启动时可以直接从本地读取不用依赖 Metro 服务或者远程加载。检查完这三个点壳工程的基本配置就算到位了。这个阶段经常出现的问题是模板生成的配置和当前 rnoh 版本不完全一致如果编译报错优先看官方模板仓库里对应的版本分支。3.3 原生模块桥接让JS调用鸿蒙能力壳工程跑通之后核心工作就变成写鸿组件了。所谓鸿组件本质上是通过 rnoh 提供的能力把一段鸿蒙原生代码封装成 JS 侧可以调用的模块。以设备信息模块为例JS 侧是这样用的import { NativeModules } from react-native; const DeviceBridge NativeModules.HarmonyDeviceBridge; async function getDeviceName() { const name await DeviceBridge.getDeviceName(); return name; }鸿蒙侧要做的事是实现 rnoh 的 TurboModule 接口然后在模块注册表里登记。大致思路是这样// 鸿蒙侧定义本地模块 export class HarmonyDeviceBridge implements TurboModule { getName(): string { return HarmonyDeviceBridge; } getDeviceName(): Promisestring { // 调用系统能力返回设备名称 return Promise.resolve(deviceInfo.name); } }注意事项是rnoh 的原生模块 API 在不同版本里会演进写代码前一定要以当前版本自带的模板和文档为准。我这里给的是概念性示例实际创建模块推荐走 CLI 模板生成的脚手架在里面填充业务逻辑即可。桥接层设计上我有一条经验不要贪多。一开始只暴露真正底层、真正需要鸿蒙系统能力的方法比如分布式文件读写、设备信息、推送 token 获取。等跑熟了再逐步扩展。把整个业务逻辑全部下沉到原生侧会让 JS 侧失去灵活性后续调试会很痛苦。3.4 构建、安装与调试鸿蒙侧的编译工具是 hvigor对应命令是# 在 harmony 目录下执行 hvigorw assembleHap成功之后会生成 HAP 安装包。连上真机后用 hdcHarmonyOS Device Connector命令行工具安装hdc list targets hdc install entry/build/default/outputs/default/entry-default-signed.hap调试阶段RN 的 JS 代码还是走 Metro 标准流程。启动 Metro然后在 DevEco Studio 里以 debug 模式运行RN 页面会加载 Metro 提供的 bundle支持热更新。鸿蒙侧的系统日志则可以用 hdc 查看hdc log我的实操心得是JS 侧问题看 Metro 输出原生侧问题看 hdc log两个日志同时开着对照。RN 业务出问题报错大多在 JS 层组件不渲染、白屏、崩溃多半要去原生日志里查 ArkUI 渲染链路和 rnoh 模块注册信息。4. 跑起来之后最磨人的事启动白屏4.1 白屏在鸿蒙场景下的根因拆解热搜词里“react native 启动白屏”高居不下不是没原因的。白屏是所有 RN 跨端项目都会遇到的问题在鸿蒙上尤其明显。从启动链路拆开看RN 页面从点开应用到首帧渲染要经过这么几段UIAbility 冷启动创建主线程和窗口。rnoh 运行时初始化加载 RN 的 C 核心和 Hermes 引擎。读取并执行 JS Bundle。如果 bundle 很大这个步骤很耗时。JS 执行 React 组件渲染逻辑生成虚拟节点树。通过渲染层把节点映射到 ArkUI完成首帧绘制。这条链路上任何一个环节慢一点表现就是用户盯着白屏。鸿蒙场景下有几个叠加因素UIAbility 冷启动的开销、ArkUI 组件树初始构建的时间、Hermes 引擎在鸿蒙运行时的首次初始化。如果再把网络加载 bundle 算进去白屏时间可以轻松拉到几秒。4.2 排查白屏的日志读法白屏问题之所以难搞是因为它可能出在原生层也可能出在 JS 层。我的排查顺序是先分两类看 JS 有没有跑起来再看原生渲染有没有完成。第一步看 Metro 或打包日志确认 bundle 是否被正确加载。如果 bundle 路径配错、资源没装进去JS 根本没执行屏幕上自然什么都没有。第二步在 hdc log 里过滤 rnoh 和 ReactNativeJS 关键字。如果 JS 已经执行但 ArkUI 没渲染出来问题大概率出在组件映射或原生渲染层如果 JS 崩溃日志里会留下完整的异常堆栈这时候就回到 RN 侧排查代码。第三步使用 DevEco Studio 自带的启动分析器看从启动到首帧的耗时分布。有一次我们排查白屏发现问题出在 UIAbility 的onCreate里做了大量初始化把首帧硬生生拖慢了 1.2 秒。把无关初始化移到后台任务后白屏时间明显下降。一个重要提示白屏排查不要凭感觉改代码。先量化再定位最后动手。没有 Profile 数据支撑的优化大多数时候都是在碰运气。4.3 首屏提速方案实测针对白屏我实际试过的有效方案可以整理成一套组合拳。启动图兜底在 UIAbility 的启动窗口上配置启动图RN 首帧渲染完成后再隐藏。用户感知上不再是白屏而是“启动图持续了一小会儿”。Bundle 本地内置把 JS Bundle 打包进 HAP 的 rawfile启动时直接从本地读取避免网络加载。Hermes 字节码预编译发布构建时用 Hermes 把 JS Bundle 编译成字节码减少引擎执行时的解释开销。首屏组件瘦身把首屏的组件树尽量压平减少嵌套层级。深层次、重状态的组件放到二次渲染再加载。延迟非关键任务JS 侧初始化的网络请求、埋点、广告配置等全部延后到首帧之后执行。我这里不搞抽象直接说明效果。我们其中一次优化启动到首帧的时间从 2.8 秒压到了 1.6 秒左右主要收益来自启动图、本地 Bundle 和首屏瘦身三项。Hermes 字节码在鸿蒙上也有收益但提升幅度不如安卓明显可能跟运行时的适配成熟度有关建议你们也测一下再做决定。5. 鸿蒙适配的避坑清单与技术路线反思5.1 从安卓思维迁移到鸿蒙思维适配过程中我们整理了一份内部避坑清单基本都是血泪图片资源别用安卓的 drawable 命名规则鸿蒙用 media 目录名称和使用方式都有区别。字体注册方式和安卓不同某些第三方字体包需要单独适配。深色模式不能直接沿用安卓的主题切换鸿蒙有自己的主题配置体系。权限模型差异巨大module.json5里声明权限、运行时申请的逻辑都要重写。第三方原生库基本不能直接复用RN 生态里未适配鸿蒙的原生模块需要找替代方案或自己封装。API 版本迭代很快时机不凑巧的话同一套代码换 SDK 版本就会出现编译差异。对 RN 团队来说最大的敌人是“惯性”。我们的做法是定一个规矩任何模块先在鸿蒙官方文档里查正向术语和设计范式再动手写桥接代码。用安卓的思路写鸿蒙代码写出来的东西大概率是歪的。5.2 RN与uniapp、原生开发怎么选迁移过程中免不了被问到技术选型问题尤其是和 uniapp 的横向对比。我做了一个简化版的比较维度React Native (rnoh)uni-app / uni-app x原生鸿蒙开发语言生态React JS/TSVue JSArkTS鸿蒙适配成熟度社区持续演进中uni-app x 有专门鸿蒙方案系统级完整支持跨端复用度高RN 代码基本复用高尤其同时做小程序单独一套代码性能上限接近原生依赖适配依赖编译方案最高团队上手成本RN 团队零成本前端团队友好需要单独学习原生能力覆盖需要桥接封装部分系统能力受限完整我的判断是如果团队已经有成规模的 RN 工程当前阶段选择 rnoh 适配是最务实的路径能把迁移成本压到最低如果是从零开始且以鸿蒙为主要阵地原生 ArkTS 体验最好如果团队主要做小程序生态uniapp 的那套方案可以认真评估。技术选型没有绝对最优只有匹配团队现状和业务重心的方案。5.3 团队怎么排兵布阵与激励热词里提到“鸿蒙开发激励”说明企业对这块是有预期的。结合我们自己的经历团队落地时有一个经验可以分享不要一上来就铺开做全部业务适配。我们是分三步走的。第一步挑一个低频、非核心的页面做试点跑通完整链路解决工具链问题。第二步把核心的基础组件网络层、图片层、存储层封装成鸿组件供后续页面复用。第三步再逐步把核心业务页面迁过去每迁一个页面就沉淀一份适配记录。激励上除了公司层面的激励外团队内部也在做“组件归属制”。某个组件谁完成桥接谁就是该组件的技术负责人后续维护和扩展都归他。这种方式比单纯发奖金更能驱动工程质量的沉淀。最后分享一个小习惯回头总结RN 跑鸿蒙这事最怕的不是技术门槛而是用安卓的惯性思维去套鸿蒙的架构。我踩过最深的坑就是一开始没锁版本、硬套旧文档结果整个构建链全错。后来我们定了规矩先固定 RN 版本、rnoh 版本、HarmonyOS API 版本三件套再动手改代码新开任何模块先查 ArkTS 的约束再写 JS 侧接口。这两个习惯帮我省掉了大量的返工时间。如果你也在做同样的迁移先从最小的试点页面开始别急着把整套业务搬上去。跑通一条链路带来的信心和经验积累比看十篇文档都管用。后面我们在组件封装和分布式能力桥接上有了新进展会继续把细节放出来。
React Native鸿蒙适配实战：从架构认知到鸿组件开发
最近我身边好几个做 React Native 的同行都在聊“鸿蒙开发激励”这件事。有的公司给鸿蒙方向单开了预算有的团队把鸿蒙适配列进了今年的硬指标招聘软件上“鸿蒙开发工程师”的岗位也明显多了起来。我们小组年初开了几次会最终定下一个方向现有 RN 代码不推倒重写但要尽快跑通“React Native 代码在 HarmonyOS 上跑起来”这条链路。真正动手之后才发现标题里那句“在 React Native 中开发鸿组件鸿蒙组件”背后要解决的事情比想象中多得多。首先得补鸿蒙开发的基础认知比如 ArkTS、ArkUI、Stage 模型这些和安卓完全不同的概念其次要解决 RN 工程与鸿蒙应用的集成问题这涉及到工具链、构建方式、原生模块桥接最后才是把一个个业务组件真正封装成可复用的鸿组件。这篇文章就是把整套过程里我想明白的东西和踩过的坑记录下来给同样在评估 RN 加鸿蒙这条路的同学一个参考。1. 基础是关键先把鸿蒙OS的地基摸清楚1.1 鸿蒙OS不是安卓换皮架构层面到底换了什么先说一个很多人容易踩的认知误区。早期 HarmonyOS 兼容安卓 APK于是不少开发者默认“鸿蒙就是安卓换皮把我的 RN 工程打包成 APK 能装上去就能直接跑”。这个认知在 HarmonyOS NEXT 这一代是要出事的——NEXT 已经去掉了 AOSP 兼容层APK 装不了以前安卓那种“写一次到处跑”的惯性思维直接失效。从开发层面看鸿蒙和安卓几乎每个环节都不一样。语言从 Java/Kotlin 变成了 ArkTSUI 框架从 View/XML 变成了 ArkUI 声明式写法应用模型从安卓四大组件变成了 Ability 组件模型构建工具从 Gradle 换成了 hvigor包管理从 Maven 换成了 ohpm。工程结构、签名机制、资源目录、权限模型也各有各的规矩。我列了一个对比表方便从安卓转过来的同学快速建立坐标系维度Android 传统开发HarmonyOS NEXT 开发开发语言Java / KotlinArkTSTS 子集加严格约束UI 框架View XML 布局ArkUI 声明式组件模型应用入口Activity / Service 等四大组件UIAbility / ExtensionAbility构建工具Gradlehvigor包管理Maven / Gradle 依赖ohpm安装包APKHAP运行环境ART 虚拟机ArkCompiler 运行时跨设备能力弱需自行实现分布式软总线原生支持看完这张表应该能明白一件事鸿蒙不是安卓的更新版是另一套独立系统。RN 团队做适配时最忌讳的就是拿安卓项目里的那套配置和经验硬套。踏踏实实把鸿蒙的开发范式重新学一遍后面反而更顺利。1.2 “分布式”三个字落到开发上意味着什么鸿蒙OS 对外最常提的是“分布式操作系统”这个概念的份量比宣传语要重。传统手机系统是以单设备为中心应用跑在手机上数据和任务都跟着手机走。鸿蒙的底层设计则是以“多设备协同”为中心设备之间通过分布式软总线进行通信发现、组网、传输都不需要路由器中转手机、平板、智慧屏、手表可以拧成一个逻辑上的“超级终端”。对做 RN 桥接的开发者来说分布式最直接的影响是你在鸿蒙侧封装组件时能力边界不再局限于一台设备。比如一个跨设备文件传输组件、一个分布式数据同步组件、一个任务流转组件这些都是鸿蒙侧原生的系统能力可以通过桥接层暴露给 JS 侧调用。这意味着什么意味着设计鸿组件时API 的输入输出不能只想着“本机数据”。举例来说跨端同步一份笔记内容组件要考虑远端设备不在线时的状态反馈、同步冲突如何处理、页面在流转过程中生命周期怎么保存。这些在传统 RN 组件里很少碰到但是在鸿蒙场景下是核心体验的一部分。如果只是把原来的网络请求组件搬过去等于浪费了鸿蒙最大的差异化优势。1.3 ArkTS极其严格TS的野路子先收一收要说鸿蒙开发基础里对 RN 团队“杀伤力”最大的一点我首推 ArkTS 的约束性。ArkTS 在 TypeScript 基础上做了一套更严格的限制目的是让代码可以静态分析、让方舟编译器做深度优化。但副作用就是TS 里很多“自由世界”的写法在 ArkTS 里直接编译不过。具体踩坑包括不推荐或不允许使用any类型不支持解构赋值至少某些场景下受限不允许动态给对象/类添加属性对Object字面量的写法有额外要求部分泛型边界也有自己的一套规则。前端和 RN 开发者写惯了 TS 的各种 trick跑到 ArkTS 里会发现一大批第三方库过不了编译。这个约束对 RN 集成的影响是真实的。RN 生态里大量 npm 包都是常规 TS 写法部分包在鸿蒙侧直接编译会报错。我们当时的应对策略是把所有原生模块的 JS 侧接口统一收敛到一个封装层封装层内部做类型清理对外暴露的接口尽量是简单的string、number、PromiseT避免把第三方包的类型系统直接铺到 ArkTS 边缘。代价是多写一层胶水代码但换来的是整个工程的稳定性。所谓“鸿组件”鸿蒙组件其实就是在这个封装层之上沉淀出来的产物JS 侧提供稳定的 React 组件接口鸿蒙侧通过 rnoh 的模块注册机制把原生能力注册进去两边各司其职。开发它的前提就是上面这套鸿蒙基础认知得先立住。2. 架构决定接入方式RN为什么能跑在鸿蒙上2.1 先搞清楚RN的“三层模型”与新架构要理解 RN 在鸿蒙上怎么跑得先知道 RN 本身是怎么组织的。经典架构下RN 内部有三条业务链路JS 线程负责运行业务逻辑Shadow 线程负责计算虚拟节点树和布局UI 线程负责真正渲染。JS 侧和原生侧之间靠 Bridge 通信Bridge 会把调用序列化后批量发送效率不高而且数据类型要能 JSON 序列化。新架构Fabric TurboModule JSI重点解决了两件事。第一件JSI 取代了 BridgeJS 对象和 C 对象之间可以互操作不再需要全量序列化。第二件Shadow 树移到了 C 层统一管理渲染管线更清晰。也就是说新架构下 RN 的核心引擎本身是跨平台的 C 实现真正依赖平台的只有线程绑定、UI 渲染接口和原生模块的实现细节。这也是 RN 能在鸿蒙上落地的架构基础。只要把平台相关的那部分换成鸿蒙能力C 核心不动JS 业务代码几乎原样保留RN 就能跑起来。2.2 rnoh做了什么事社区主导的 rnohReact Native OpenHarmony项目干的就是这件“换平台实现”的事。它通过 N-APINode-API把 RN 的 C 核心接到鸿蒙的运行时上渲染层走 ArkUI 的组件树原生模块走鸿蒙侧的 TurboModule 实现。简单说rnoh 做的事情可以理解为三层JS 业务代码照常写 React 组件、Hooks、状态管理这部分完全复用。RN 的引擎核心C 部分通过鸿蒙提供的 N-API 运行起来。RN 的 View/Text/Image 等基础组件映射到 ArkUI 对应的原生组件布局计算出来后渲染到 ArkUI 的树里。这条技术路线的好处很清楚RN 团队不需要自己包一层鸿蒙 WebView不需要把业务代码重写成 ArkTS也不需要维护两套 UI。组件映射、模块桥接这些脏活由 rnoh 承担业务层改动被压到最小。实际体验下来RN 的 JS 侧能调用的基础组件和模块基本都能用第三方组件库则需要看是否适配了鸿蒙。2.3 版本对应关系先锁死不然装完就报错RN 上鸿蒙最让人头大的不是架构是版本矩阵。RN 版本、rnoh 版本、DevEco Studio 版本、HarmonyOS SDK 版本、hvigor 版本、Node 版本、JDK 版本七个变量互相咬合。任何一个对不上安装依赖或编译时就会冒出各种莫名其妙的报错。我的建议是动手之前先定死“三件套”。RN 版本锁死你当前项目用的版本不要顺手升级。rnoh 版本选择与该 RN 版本匹配的 rnoh 版本以官方 Release Note 为准。HarmonyOS API 版本对应 DevEco Studio 里的 SDK 版本。原因在于rnoh 的适配工作是跟着 RN 版本走的比如某个 rnoh 版本针对 RN 0.72、另一个针对 0.73用错组合就会出现模块找不到、组件注册失败、编译期符号缺失等一系列问题。我们第一次接入时没锁版本照着旧文档硬配结果构建链全线报错排查了两天最后发现就是版本错位。所以这一步别嫌麻烦先看官方文档的版本对应表再动手。3. 实操把RN工程接进鸿蒙的完整步骤3.1 准备工具链DevEco Studio、签名与真机在真正写代码之前先把环境准备好。安装 DevEco Studio装好后在 SDK Manager 里拉取对应版本的 HarmonyOS SDK。配置 Node.js 和 JDK版本要求按 DevEco Studio 官方说明来。准备一台 HarmonyOS NEXT 真机或者用 DevEco 自带的模拟器。注册华为开发者账号申请调试证书和 Profile这个环节是必做的没有签名配置HAP 装不到真机上。签名这步容易掉坑。安卓开发时 debug 签名通常是自动生成的鸿蒙侧则要手动配置。需要在 AppGallery Connect 里创建项目生成证书和 Profile然后把证书文件下载到本地之后在工程的build-profile.json5里指定签名信息。我们团队第一次弄的时候在证书类型、包名、Profile 的绑定关系上卡了一天。建议仔细看官方文档的“应用签名”章节把包名从头到尾统一避免改来改去。3.2 生成鸿蒙壳工程与核心配置当环境就绪后这才是真正的集成起点。rnoh 提供了 CLI 工具可以从现有 RN 项目生成一份鸿蒙壳工程。实际操作中我的流程大致如下# 先安装 rnoh 核心库 npm install rnoh/react-native-harmony # 使用 CLI 生成鸿蒙工程 npx react-native-harmony-cli --output harmony执行后项目根目录下会多出一个harmony文件夹。里面能看到AppScope/、entry/、build-profile.json5、oh-package.json5、hvigorfile.ts这些鸿蒙特有文件。接下来要做的配置有三个重点。第一把鸿蒙应用包名和签名信息配置到build-profile.json5的signingConfigs里。这里需要填证书文件路径、Profile 路径和密码具体字段名以当前 DevEco Studio 版本为准。第二在entry/src/main/module.json5里确认 UIAbility 的配置文件。默认生成的壳工程已经包含页面入口逻辑RN 业务会加载到这个 Ability 中。第三把 RN 的 JS Bundle 打包到鸿蒙侧的 assets 目录。可以在 RN 工程里加一条打包脚本把 bundle 打进entry/src/main/resources/rawfile/下这样 App 启动时可以直接从本地读取不用依赖 Metro 服务或者远程加载。检查完这三个点壳工程的基本配置就算到位了。这个阶段经常出现的问题是模板生成的配置和当前 rnoh 版本不完全一致如果编译报错优先看官方模板仓库里对应的版本分支。3.3 原生模块桥接让JS调用鸿蒙能力壳工程跑通之后核心工作就变成写鸿组件了。所谓鸿组件本质上是通过 rnoh 提供的能力把一段鸿蒙原生代码封装成 JS 侧可以调用的模块。以设备信息模块为例JS 侧是这样用的import { NativeModules } from react-native; const DeviceBridge NativeModules.HarmonyDeviceBridge; async function getDeviceName() { const name await DeviceBridge.getDeviceName(); return name; }鸿蒙侧要做的事是实现 rnoh 的 TurboModule 接口然后在模块注册表里登记。大致思路是这样// 鸿蒙侧定义本地模块 export class HarmonyDeviceBridge implements TurboModule { getName(): string { return HarmonyDeviceBridge; } getDeviceName(): Promisestring { // 调用系统能力返回设备名称 return Promise.resolve(deviceInfo.name); } }注意事项是rnoh 的原生模块 API 在不同版本里会演进写代码前一定要以当前版本自带的模板和文档为准。我这里给的是概念性示例实际创建模块推荐走 CLI 模板生成的脚手架在里面填充业务逻辑即可。桥接层设计上我有一条经验不要贪多。一开始只暴露真正底层、真正需要鸿蒙系统能力的方法比如分布式文件读写、设备信息、推送 token 获取。等跑熟了再逐步扩展。把整个业务逻辑全部下沉到原生侧会让 JS 侧失去灵活性后续调试会很痛苦。3.4 构建、安装与调试鸿蒙侧的编译工具是 hvigor对应命令是# 在 harmony 目录下执行 hvigorw assembleHap成功之后会生成 HAP 安装包。连上真机后用 hdcHarmonyOS Device Connector命令行工具安装hdc list targets hdc install entry/build/default/outputs/default/entry-default-signed.hap调试阶段RN 的 JS 代码还是走 Metro 标准流程。启动 Metro然后在 DevEco Studio 里以 debug 模式运行RN 页面会加载 Metro 提供的 bundle支持热更新。鸿蒙侧的系统日志则可以用 hdc 查看hdc log我的实操心得是JS 侧问题看 Metro 输出原生侧问题看 hdc log两个日志同时开着对照。RN 业务出问题报错大多在 JS 层组件不渲染、白屏、崩溃多半要去原生日志里查 ArkUI 渲染链路和 rnoh 模块注册信息。4. 跑起来之后最磨人的事启动白屏4.1 白屏在鸿蒙场景下的根因拆解热搜词里“react native 启动白屏”高居不下不是没原因的。白屏是所有 RN 跨端项目都会遇到的问题在鸿蒙上尤其明显。从启动链路拆开看RN 页面从点开应用到首帧渲染要经过这么几段UIAbility 冷启动创建主线程和窗口。rnoh 运行时初始化加载 RN 的 C 核心和 Hermes 引擎。读取并执行 JS Bundle。如果 bundle 很大这个步骤很耗时。JS 执行 React 组件渲染逻辑生成虚拟节点树。通过渲染层把节点映射到 ArkUI完成首帧绘制。这条链路上任何一个环节慢一点表现就是用户盯着白屏。鸿蒙场景下有几个叠加因素UIAbility 冷启动的开销、ArkUI 组件树初始构建的时间、Hermes 引擎在鸿蒙运行时的首次初始化。如果再把网络加载 bundle 算进去白屏时间可以轻松拉到几秒。4.2 排查白屏的日志读法白屏问题之所以难搞是因为它可能出在原生层也可能出在 JS 层。我的排查顺序是先分两类看 JS 有没有跑起来再看原生渲染有没有完成。第一步看 Metro 或打包日志确认 bundle 是否被正确加载。如果 bundle 路径配错、资源没装进去JS 根本没执行屏幕上自然什么都没有。第二步在 hdc log 里过滤 rnoh 和 ReactNativeJS 关键字。如果 JS 已经执行但 ArkUI 没渲染出来问题大概率出在组件映射或原生渲染层如果 JS 崩溃日志里会留下完整的异常堆栈这时候就回到 RN 侧排查代码。第三步使用 DevEco Studio 自带的启动分析器看从启动到首帧的耗时分布。有一次我们排查白屏发现问题出在 UIAbility 的onCreate里做了大量初始化把首帧硬生生拖慢了 1.2 秒。把无关初始化移到后台任务后白屏时间明显下降。一个重要提示白屏排查不要凭感觉改代码。先量化再定位最后动手。没有 Profile 数据支撑的优化大多数时候都是在碰运气。4.3 首屏提速方案实测针对白屏我实际试过的有效方案可以整理成一套组合拳。启动图兜底在 UIAbility 的启动窗口上配置启动图RN 首帧渲染完成后再隐藏。用户感知上不再是白屏而是“启动图持续了一小会儿”。Bundle 本地内置把 JS Bundle 打包进 HAP 的 rawfile启动时直接从本地读取避免网络加载。Hermes 字节码预编译发布构建时用 Hermes 把 JS Bundle 编译成字节码减少引擎执行时的解释开销。首屏组件瘦身把首屏的组件树尽量压平减少嵌套层级。深层次、重状态的组件放到二次渲染再加载。延迟非关键任务JS 侧初始化的网络请求、埋点、广告配置等全部延后到首帧之后执行。我这里不搞抽象直接说明效果。我们其中一次优化启动到首帧的时间从 2.8 秒压到了 1.6 秒左右主要收益来自启动图、本地 Bundle 和首屏瘦身三项。Hermes 字节码在鸿蒙上也有收益但提升幅度不如安卓明显可能跟运行时的适配成熟度有关建议你们也测一下再做决定。5. 鸿蒙适配的避坑清单与技术路线反思5.1 从安卓思维迁移到鸿蒙思维适配过程中我们整理了一份内部避坑清单基本都是血泪图片资源别用安卓的 drawable 命名规则鸿蒙用 media 目录名称和使用方式都有区别。字体注册方式和安卓不同某些第三方字体包需要单独适配。深色模式不能直接沿用安卓的主题切换鸿蒙有自己的主题配置体系。权限模型差异巨大module.json5里声明权限、运行时申请的逻辑都要重写。第三方原生库基本不能直接复用RN 生态里未适配鸿蒙的原生模块需要找替代方案或自己封装。API 版本迭代很快时机不凑巧的话同一套代码换 SDK 版本就会出现编译差异。对 RN 团队来说最大的敌人是“惯性”。我们的做法是定一个规矩任何模块先在鸿蒙官方文档里查正向术语和设计范式再动手写桥接代码。用安卓的思路写鸿蒙代码写出来的东西大概率是歪的。5.2 RN与uniapp、原生开发怎么选迁移过程中免不了被问到技术选型问题尤其是和 uniapp 的横向对比。我做了一个简化版的比较维度React Native (rnoh)uni-app / uni-app x原生鸿蒙开发语言生态React JS/TSVue JSArkTS鸿蒙适配成熟度社区持续演进中uni-app x 有专门鸿蒙方案系统级完整支持跨端复用度高RN 代码基本复用高尤其同时做小程序单独一套代码性能上限接近原生依赖适配依赖编译方案最高团队上手成本RN 团队零成本前端团队友好需要单独学习原生能力覆盖需要桥接封装部分系统能力受限完整我的判断是如果团队已经有成规模的 RN 工程当前阶段选择 rnoh 适配是最务实的路径能把迁移成本压到最低如果是从零开始且以鸿蒙为主要阵地原生 ArkTS 体验最好如果团队主要做小程序生态uniapp 的那套方案可以认真评估。技术选型没有绝对最优只有匹配团队现状和业务重心的方案。5.3 团队怎么排兵布阵与激励热词里提到“鸿蒙开发激励”说明企业对这块是有预期的。结合我们自己的经历团队落地时有一个经验可以分享不要一上来就铺开做全部业务适配。我们是分三步走的。第一步挑一个低频、非核心的页面做试点跑通完整链路解决工具链问题。第二步把核心的基础组件网络层、图片层、存储层封装成鸿组件供后续页面复用。第三步再逐步把核心业务页面迁过去每迁一个页面就沉淀一份适配记录。激励上除了公司层面的激励外团队内部也在做“组件归属制”。某个组件谁完成桥接谁就是该组件的技术负责人后续维护和扩展都归他。这种方式比单纯发奖金更能驱动工程质量的沉淀。最后分享一个小习惯回头总结RN 跑鸿蒙这事最怕的不是技术门槛而是用安卓的惯性思维去套鸿蒙的架构。我踩过最深的坑就是一开始没锁版本、硬套旧文档结果整个构建链全错。后来我们定了规矩先固定 RN 版本、rnoh 版本、HarmonyOS API 版本三件套再动手改代码新开任何模块先查 ArkTS 的约束再写 JS 侧接口。这两个习惯帮我省掉了大量的返工时间。如果你也在做同样的迁移先从最小的试点页面开始别急着把整套业务搬上去。跑通一条链路带来的信心和经验积累比看十篇文档都管用。后面我们在组件封装和分布式能力桥接上有了新进展会继续把细节放出来。
