年初把团队的主力 React Native 项目往 HarmonyOS 设备上迁移时我心里其实没底。RN 在 Android 和 iOS 上的套路已经熟了但鸿蒙不是简单的“第三个移动平台”它有自己的 ArkTS、ArkUI、Stage 模型还有一套完全独立于 Android 的原生组件体系。要让一套 JS 代码在鸿蒙上跑起来中间隔着的不是一层薄薄的适配而是“原生鸿蒙组件 RN 桥接层 鸿蒙应用模型”这三件事。这篇文章就是想把这三件事串起来鸿蒙开发的基础到底要补哪些React Native 工程怎么和鸿蒙应用集成以及在 RN 里写一个鸿蒙原生组件时会踩到哪些坑。我默认看这篇文章的你至少用 React Native 写过业务但对鸿蒙属于“知道但没上手”。如果你正在做 RN 鸿蒙化改造或者准备在新项目里同时支持 Android、iOS、鸿蒙这篇文章能帮你少走很多弯路。我尽量把关键步骤和反例都写出来特别是一些你上网搜不到答案的细节比如启动白屏到底怎么看日志、原生组件的事件穿透怎么处理、工具链部署失败往往卡在哪个环节。1. 在 React Native 中接入鸿蒙先要搞清楚的几个底层问题1.1 React Native 的渲染链路在鸿蒙上是怎么走的React Native 在原生平台上的渲染链路本质上是一套“JS 描述 UI、原生负责渲染”的机制。JavaScript 跑在 Hermes 或 JSC 引擎里通过 Bridge 或者新一代的 TurboModule 把组件树的操作发给原生端原生端再调用平台自己的 UI 系统把界面画出来。在 Android 上RN 的底层对应的是 Android View在 iOS 上对应的是 UIView到了鸿蒙对应的就是 ArkUI 的组件树和原生组件。这个对应关系非常关键。很多人以为鸿蒙支持 RN 是把 WebView 套了一层壳或者用某个兼容层把 Android 代码翻译过来其实不是。真正要跑起来必须有人为鸿蒙实现一套 RN 的“原生渲染后端”。也就是说RN 框架需要的原生模块、UI 组件管理器、事件分发器在鸿蒙上都要有对应的实现。这就是社区里那些react-native-harmony、react-native-openharmony这类项目在做的事。理解了这一点你就知道为什么“RN 在鸿蒙上白屏”是一个高频问题。任何一环断了比如 JS bundle 没加载、原生组件注册失败、ArkUI 容器没创建成功最后表现都是白屏。而排查白屏也必须从这条渲染链路的每一层去查不能只盯 JS 代码。1.2 鸿蒙开发基础到底指什么如果你是从 RN 转过来的尤其是以前只写过 JS/TS会觉得鸿蒙开发有点“既熟悉又陌生”。熟悉的是 ArkTS 语法基本就是 TypeScript 的严格子集声明式 UI 的风格也和 React 很接近。陌生的是它背后的应用模型和工程组织方式这跟 Android/iOS 差异很大。我建议你把鸿蒙开发基础拆成三块来看。第一块是 ArkTS 语言。它限制了很多动态特性比如不支持any对象字面量必须对应明确接口必须显式标注类型。对于常年写 TS 的人适应成本不高但如果你习惯了 JS 的随意一开始会被编译器教训得很惨。第二块是 ArkUI 声明式 UI。它用Component、Entry、State这类装饰器来声明页面结构写法上有点像 React 的函数组件加 Hooks但背后的状态管理、渲染更新机制完全是自己的。你要开发一个给 RN 用的鸿蒙原生组件核心就是在 ArkUI 的组件体系里写一个满足 RN 接口的“宿主组件”。第三块是 Stage 应用模型。每个鸿蒙应用有入口UIAbility类似 Android 的 Activity 或 iOS 的 UIWindowScene。页面和页面之间的跳转基于WindowStage生命周期也要遵循鸿蒙的规则。RN 的鸿蒙适配层本质上是把 RN 的根容器嵌入到一个UIAbility的窗口里。这三块是绕不开的。就算你只打算写一个简单的原生组件也必须知道组件最终是挂在哪个Ability的窗口上因为这会直接影响生命周期和内存回收。1.3 技术选型用官方适配库还是自己桥接RN 接鸿蒙现实的选择有两种用社区现成的适配框架或者自己基于鸿蒙 SDK 桥接。现成的框架目前主要看react-native-harmonyRNOH这条线。它已经帮我们解决了 JS 引擎、渲染层、原生模块通信这些最脏最累的活而且还提供了像rnoh/react-native-openharmony这种按需引入的包。如果你的项目用的是 React Native 0.71 之后的版本直接用社区脚手架初始化鸿蒙工程是很顺畅的。自己桥接听起来很极客但我不推荐在项目初期做。原因是 RN 和鸿蒙的通信机制并不是简单的一对一映射里面有 JS 引擎的生命周期管理、组件树的异步 diff、事件回传的线程模型还有很多边界情况。除非你的业务很特殊必须深度定制某个硬件能力否则先用上层适配库把业务跑通再考虑自己扩展原生模块是最稳的路线。选型时还要考虑团队的组成。如果团队里有人懂鸿蒙原生可以选择更灵活的半自研如果全员都是 RN 出身我建议死磕 RNOH 生态尽量用标准接口避免落入维护自定义桥接的坑。2. 鸿蒙开发基础搭建环境与理解核心模型2.1 开发环境与工具链开始之前先把环境搭好。鸿蒙原生开发用的 IDE 是 DevEco Studio它内置了 HarmonyOS SDK、模拟器、签名工具和 hvigor 构建系统。你下载安装之后会看到它和我们熟悉的 Android Studio 布局很接近左边是项目结构右边是预览器底部是日志面板。第一次启动可能会提示下载 SDK别跳过。环境变量需要注意。DevEco Studio 默认会把 SDK 装到用户目录下比如 macOS 上的~/Library/Huawei/SdkWindows 上可能是C:\Users\xxx\AppData\Local\Huawei\Sdk。后面我们在 RN 工程里跑鸿蒙构建脚本时经常要读取这个路径最好把它设成环境变量避免每次构建都要传参。这里我想多说一句关于“部署 HarmonyOS 7 失败”的问题最近不少人在社区反馈类似的一键部署或安装脚本跑着跑着就挂了。我踩过的坑主要有三类第一SDK 版本和 DevEco Studio 版本不匹配构建工具拿到一个不认识的 SDK 路径第二Node.js 版本太新或太旧导致 hvigor 脚本执行异常第三权限不足写不到系统目录或缓存目录。遇到部署失败先不要急着重装打开终端把报错完整粘出来先看路径和版本号再决定下一步。2.2 ArkTS 语法要点与常见误区ArkTS 是 TS 的严格超集但它把很多 JS 里的“野路子”都禁掉了。举个例子普通 TS 里你写let data: any getSomething()很常见但在 ArkTS 里直接不允许any。你得把类型定义清楚要么用联合类型要么用unknown加类型收窄。这个限制对开发 RN 桥接代码尤其重要因为 JS 和原生之间的数据往往没有静态类型你需要自己在边界处定义好类型接口否则编译期就过不去。另一个容易踩的坑是对象字面量。ArkTS 要求对象字面量必须对应一个明确的 class 或 interface不能像 JS 一样随意return { name: test, value: 1 }。这意味着你在写原生组件属性映射时一定要先声明一个 interface所有属性都要走编译期检查。ArkTS 也支持装饰器这是它跟 React 最大的区别。你会在代码里看到Entry、Component、State、Prop这样的写法。特别是State它标识的变量一旦变化UI 会自动刷新类似 React 的useState触发的重渲染。对于原生组件这种响应式能力要谨慎使用因为 RN 侧的状态更新其实是从 JS 发过来的如果两边同时触发状态刷新很容易出现渲染闪烁。2.3 Stage 模型与 UIAbility 的生命周期在鸿蒙上应用不再像 Android 那样有一个全局的 Application 和一堆 Activity而是用 Stage 模型来组织。一个应用可以有多个 Module每个 Module 有自己的入口 Ability。UIAbility是页面能力的载体它和窗口、页面路由、生命周期事件都有直接关系。我们做 RN 集成的第一步是创建一个自己的UIAbility用来承载 RN 的根视图。这个 Ability 的生命周期方法会直接影响到 RN 应用的表现。比如onCreate适合做初始化但不适合直接渲染onWindowStageCreate才是拿到WindowStage、加载 UI 内容的地方。你要在这个方法里创建WindowStage的loadContent把 RN 容器组件加载进去。如果在这个时机之前就去访问窗口大概率会得到空对象然后在 RN 启动时崩溃或白屏。还要注意后台切回前台的场景。鸿蒙的onForeground和onBackground对应着应用的可见性变化。RN 的 JS 引擎不会因为你切到后台就自动暂停但如果你在onBackground里做了资源释放回来时一定要确保优先恢复 RN 容器否则会出现“回到应用后黑屏一会儿”的体验问题。3. React Native 与鸿蒙的集成实操3.1 初始化 RN 工程并接入鸿蒙适配层我以 React Native 0.72 以上的版本为例说明接入鸿蒙适配层的基本流程。首先创建一个标准 RN 工程npx react-native-community/clilatest init RNHarmonyDemo cd RNHarmonyDemo接着安装鸿蒙适配层相关的依赖。社区常用的包是react-native-harmony和rnoh/react-native-openharmony它们会提供鸿蒙工程模板、原生构建脚本和 JS 侧的兼容层。安装过程大概是这样npm install react-native-harmony npm install rnoh/react-native-openharmony安装完成后利用适配层提供的脚手架工具为当前 RN 工程生成鸿蒙原生工程目录。以 RNOH 为例它会在项目里生成一个harmony目录里面有entry、oh-package.json5、hvigorfile.ts这些标准鸿蒙工程文件。这一步做完你的 RN 工程就变成了一份代码、四个平台的结构android/、ios/、harmony/以及公共的src/目录。生成完目录后用 DevEco Studio 打开harmony目录让 IDE 自动同步鸿蒙依赖。首次同步会因为要拉取鸿蒙 SDK 的依赖包比较慢建议开一个稳定的网络环境慢慢等。同步完成后需要确认oh-package.json5里声明的 SDK 版本和你本机的 HarmonyOS SDK 版本一致否则构建时会直接报错。3.2 在鸿蒙工程中加载 RN 页面原生目录生成好了接下来要解决的是“鸿蒙应用启动后怎么把 RN 页面显示出来”。在鸿蒙工程里我们需要在EntryAbility中创建一个 RN 容器然后把这个容器作为页面内容加载到窗口里。这里用一个简化版的 ArkTS 代码片段来说明核心逻辑// EntryAbility.ets import { UIAbility, AbilityConstant, Want } from kit.AbilityKit; import { window } from kit.ArkUI; import { RNOHContext, RNInstance, RNHost } from react-native-harmony; export default class EntryAbility extends UIAbility { private rnHost?: RNHost; onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 初始化 RN 宿主这一步会创建 JS 引擎和原生模块管理者 this.rnHost new RNHost(this.context); } onWindowStageCreate(windowStage: window.WindowStage): void { // 必须在这里加载 RN 容器 windowStage.loadContent(pages/Index, (err) { if (err.code) { console.error(load content failed: ${JSON.stringify(err)}); return; } const ctx this.rnHost?.getRNOHContext(); ctx?.start(); }); } }看着是不是有点熟其实和 Android 里在MainActivity的onCreate里执行setContentView然后启动 RN 根视图是同一个套路。关键点在于RN 的宿主对象要在onCreate里创建而真正挂载 UI 必须在onWindowStageCreate里完成。顺序反了窗口还没准备好RN 的根视图挂不上去表现出来就是启动白屏。很多刚接触的人会误以为pages/Index就是 RN 页面其实它只是一个承载壳里面可以什么都不放真正的内容由 RN 容器动态渲染。这个壳页面的作用相当于 Android 里一个空白的FrameLayout容器。3.3 把 JS 打包成 bundle 并内置到鸿蒙工程开发环境下RN 页面可以直接连接 Metro Server 加载运行时代码。但发布到鸿蒙设备上的时候肯定不能依赖 Metro必须把 JS 打包成 bundle放到鸿蒙资源目录里由原生代码读取。打包命令和 Android/iOS 类似npx react-native bundle --platform harmony --dev false --entry-file index.js --bundle-output harmony/entry/src/main/resources/base/assets/index.bundle --assets-dest harmony/entry/src/main/resources/base/assets执行完以后assets目录下会多出index.bundle和一堆图片、字体资源。重点来了bundle 的路径必须和原生代码里读取的路径完全一致大小写、目录结构都不能错。我见过很多白屏问题最后发现是 bundle 文件放到了rawfile目录而原生代码从assets目录读取自然加载不到。还有一点HarmonyOS 的资源打包机制和 Android 不一样。放在base下的资源在不同屏幕密度、不同语言环境下会被自动覆盖如果你在resources/base/element或media里放了 JS 包有时会因为资源限定符把它过滤掉。稳妥的做法是把 bundle 放在resources/rawfile目录下然后用相对路径读取。不过具体读取方式要看你用的 RN 适配层怎么封装以它提供的默认配置为准。4. 开发一个鸿蒙原生组件并挂到 React Native 中4.1 自定义原生组件的整体流程RN 里开发原生组件本质上要做三件事在原生端实现一个容器组件在 JS 端声明一个封装组件再定义这两个端之间怎么传递属性和事件。鸿蒙端的流程也逃不开这个框架只是 API 名字不同。鸿蒙适配层通常会提供一个组件管理器和组件控制器的概念。组件管理器负责注册组件名、创建实例、绑定属性组件控制器则对应前端 JS 组件的实例处理更新和事件回调。这跟 iOS 的RCTViewManager和 Android 的ViewManager很相似。整体流程可以拆成这样在 ArkTS 侧写一个继承自基础原生组件的类重写它的测量、布局、绘制逻辑或者直接组合现有 ArkUI 组件。实现一个组件控制器类给 JS 侧暴露属性解析和事件上报方法。在 JS 侧用requireNativeComponent或codegenNativeComponent注册同一个组件名。在 JS 里使用这个组件传入属性、监听事件。4.2 实现一个示例组件滚动文本组件我拿一个“滚动文本”组件举例。假设我们想做一个 RN 能用的跑马灯原生端用 ArkUI 的Text加动画实现JS 端通过text属性传入内容。先看 ArkTS 侧的组件控制器。代码是按 RNOH 常见封装写的不同小版本 API 可能有出入但思路是一致的// MarqueeComponentController.ets import { ComponentController } from react-native-harmony; export class MarqueeComponentController extends ComponentController { private textContent: string ; // 来自 JS 的属性更新 updateProps(props: Recordstring, any) { super.updateProps(props); if (props.text ! undefined) { this.textContent props.text; this.view?.updateText(this.textContent); } } // 向 JS 侧上报事件 onMarqueeFinish() { this.emit(onFinish, { finished: true }); } }然后是一个继承基础组件类的视图。这个视图内部组合了一个Text组件并且通过定时器或动画实现滚动效果// MarqueeView.ets import { Component, Text } from kit.ArkUI; import { BaseComponent } from react-native-harmony; Component export struct MarqueeView { controller?: MarqueeComponentController; State currentText: string ; updateText(text: string) { this.currentText text; } build() { Text(this.currentText) .fontSize(20) .textOverflow({ overflow: TextOverflow.Marquee }) .maxLines(1) .onAppear(() { // 模拟滚动结束 setTimeout(() { this.controller?.onMarqueeFinish(); }, 3000); }); } }再到 JS 侧注册这个组件。我用最简单的方式不依赖 codegen// NativeMarquee.tsx import { requireNativeComponent, ViewProps, HostComponent } from react-native; interface NativeMarqueeProps extends ViewProps { text: string; onFinish?: (event: { nativeEvent: { finished: boolean } }) void; } const NativeMarquee: HostComponentNativeMarqueeProps requireNativeComponent(RNOHMarquee); export default function Marquee(props: NativeMarqueeProps) { return NativeMarquee {...props} /; }组件名必须两边一致。我这边原生注册的是RNOHMarqueeJS 端也必须用它。如果你发现渲染不出来第一步就是检查组件名大小写和前缀鸿蒙的组件注册表对名称匹配非常敏感。4.3 从 JS 调用鸿蒙原生能力原生模块除了 UI 组件我们有时还需要调用非 UI 的原生能力比如读取设备信息、触发蓝牙、使用分布式文件服务。这类需求在 RN 里叫原生模块在鸿蒙端走的是 TurboModule 或者类似机制。实现一个原生模块同样有三个步骤。第一步在 ArkTS 侧定义一个类导出方法第二步注册到模块管理器第三步在 JS 侧用TurboModuleRegistry.get或NativeModules调用。我写一个获取鸿蒙设备型号的例子// DeviceInfoModule.ets import { TurboModule } from react-native-harmony; import { deviceInfo } from kit.BasicServicesKit; export class DeviceInfoModule extends TurboModule { getDeviceModel(): string { return deviceInfo.getDeviceType() _ deviceInfo.getName(); } }注册模块// RNOHTurboModuleProvider.ets export function createTurboModuleProvider() { const provider new TurboModuleProvider(); provider.register(DeviceInfoModule, () new DeviceInfoModule()); return provider; }JS 侧调用import { TurboModuleRegistry } from react-native; interface DeviceInfoModuleSpec extends TurboModule { getDeviceModel(): string; } const DeviceInfoModule TurboModuleRegistry.getEnforcingDeviceInfoModuleSpec(DeviceInfoModule); export function getModel() { return DeviceInfoModule.getDeviceModel(); }这里最容易出问题的是方法名大小写。TurboModule 的调用协议走的是 JSI方法名是符号级的映射稍微不一致直接给你一个 undefined is not a function。遇到这种问题先确认原生方法导出的名字和 JS 接口里声明的方法名完全一致然后再去看注册表有没有把模块引进去。5. 常见问题与排查技巧5.1 启动白屏先分清是 JS 没加载还是原生层失败React Native 鸿蒙化最常见的求助帖就是“启动白屏”。我用过的排查思路先别急着改代码把问题分层。第一层看应用有没有起来。如果鸿蒙应用进程根本没有启动那是原生工程的问题比如签名错误、入口 Ability 没配置。第二层应用起来了但页面空白先看 DevEco Studio 的日志面板搜索两个关键词RNOH和ReactNative。如果日志里能看到 RN 引擎初始化成功但没有 JS 执行日志多半是 bundle 没加载到。第三层如果日志里已经有 React 渲染日志但界面还是白的那可能是原生 UI 组件没有挂载到窗口上。我个人遇到最多的白屏原因是 bundle 路径不对。因为鸿蒙工程的资源目录层级比较深打出来的 bundle 经常被放到assets的子目录里而原生代码用的是相对根目录的路径。解决方法是把 bundle 路径打出来用一个日志命令确认const bundleUrl this.rnHost?.getBundleUrl(); console.info(bundle url ${bundleUrl});如果打印出来的 URL 和你实际文件路径不一致那就去改对应配置而不是在页面代码里找问题。5.2 构建与部署失败分析这几年 HarmonyOS 新版本迭代挺快社区里各种部署工具也跟着升级。但很多人会遇到“在 HarmonyOS 7 上部署失败”的报错我觉得九成以上不是代码问题而是环境问题。我整理过一个常见的检查清单每次都按这个顺序排查确认 DevEco Studio 和 HarmonyOS SDK 版本匹配。你可以在oh-package.json5里看compileSdkVersion和targetSdkVersion再与本机的 SDK 版本对比。确认 Node.js 版本。RN 鸿蒙构建脚本依赖 Node 做资源处理和命令行脚本版本太老可能导致语法不支持太新可能导致某些依赖包兼容出错。清除缓存后再构建。在 harmony 目录下执行hvigorw clean然后删除build和.cxx缓存目录重新同步。检查签名文件。真机部署必须要有签名不能直接拿模拟器调试证书往真机上装。如果你用的是一键部署脚本或者第三方工具失败原因会被工具吞掉很多建议直接打开终端手动执行 hvigor 命令看完整的堆栈。不要怕英文报错真正的原因通常就在最后十行。5.3 调试与日志抓取鸿蒙 RN 调试比 Android 要复杂一点因为 DevEco Studio 的 Log 面板和 Metro 的调试日志是两套体系。建议同时打开两个终端窗口一个跑 Metronpm start另一个用来跑鸿蒙原生日志过滤hdc log stream | grep RNOHhdc是鸿蒙的命令行工具类似 Android 的adb。如果你没配置环境变量可以在 DevEco Studio 的安装目录下找到它。用这个命令可以实时看到 RN 在原生层打的日志配合 Metro 里的 JS 报错基本能定位大多数问题。真机调试时Metro 的端口转发也很关键。默认情况下 Metro 跑在 8081 端口真机需要通过 hdc 把设备的 8081 端口映射到电脑上hdc fport tcp:8081 tcp:8081不执行这一步设备上的鸿蒙应用连不上 Metro就会出现“加载 bundle 失败”或一直停留在启动状态。这是我第一次在鸿蒙真机上跑 RN 时被卡了最久的地方后来发现不是代码问题就是端口没转发。最后再分享一个个人习惯每次改完原生代码不要直接装到设备上先在 DevEco 里跑一遍静态检查。鸿蒙的编译器对类型要求极严很多在 Android/iOS 上完全不会报错的 JS 松散写法在 ArkTS 层会被直接拦住。与其反复编译看错误不如写边界文件时就把 interface 定义完整你会发现开发鸿蒙原生组件强制类型约束反而是件好事它能帮你提前发现很多运行时才会暴露的问题。