1. DAY 2 到底要解决什么问题如果你和我一样第一天折腾完环境大概率会冒出两个念头第一React Native 在 OpenHarmony 上真的能跑起来吗第二跑起来之后我原来那套 RN 开发经验到底有多少能直接迁移DAY 2 的训练营没有绕弯子上来就把这两个问题摆到了桌面上。这一天的主题可以概括为一句话把“React Native for OpenHarmony”后面我统一简写成 RNOH当成一条真实的生产路径去评估而不是当成一个尝鲜玩具。整天的内容都围绕一件事展开——现有 RN 工程怎么低成本迁移到开源鸿蒙生态以及迁移之后怎么保证开发体验和性能不缩水。先说结论DAY 2 并没有神奇到让你一键把三个端全搞定但它把我在第一天产生的模糊预期落到了实处。核心价值在于它把 RN 在开源鸿蒙上的边界摸得很清楚——哪些组件直接可用、哪些 API 有差异、哪些能力必须通过原生桥接自己补每一类都给了可验证的结论和可操作的方案。在进入细节之前有必要先对齐一个认知OpenHarmony 上跑 React Native并不是简单地把 Android 或 iOS 那套运行时拿过来而是有一个专门的适配层把 RN 的渲染指令映射到 OpenHarmony 上基于 ArkTS 的原生组件树。这决定了你在日常开发里会遇到很多“看起来一样但细节变了”的情况。这篇文章不是官方案例的复读机而是把我当天记下的笔记、动手验证过的结论、以及踩坑之后才理解的内容整理出来按从环境搭建到实战开发、再到调试与性能优化的顺序铺开。无论你是第一天刚装好环境还是已经有 RN 跨端经验想评估迁移成本下面这些内容应该都能省下你不少时间。2. 开盘先对齐RN 在 OpenHarmony 上的运行链路2.1 从 JS 到 ArkUI 到底走了一条什么样的路训练营上午的分享首先拆解了运行时链路这部分直接决定了后面所有排错思路。在 Android 上跑 RNJS 代码通过 JSI 直接调用原生模块和 UI 操作接口在 iOS 上也是一套类似的桥接逻辑。到了 OpenHarmony 这边适配层做的事情本质上没变你的 JS 组件最终还是被翻译成 ArkUI 的组件来渲染只是中间多了一层映射关系。可以理解成 RN 的 View 对应 ArkUI 的 Column / Stack 这类容器组件RN 的 Text 对应 ArkUI 的 TextRN 的 Image 对应 ArkUI 的 ImageRN 的 FlatList 则要拆成 ArkUI 中基于数据驱动列表的实现逻辑。这里最容易犯的错误是预期对齐。不少人一开始以为 RNOH 做到的是“JS 虚拟 DOM 直接产生 ArkUI 视图”其实没那么玄。它的本质是Facebook 开源的 React Native 框架本身仍然是跑在 JavaScript 引擎上的页面描述和状态管理都发生在 JS 层OpenHarmony 适配层做的是把 React 元素树渲染到 ArkUI 组件树上。理解了这一点你就会明白为什么那么在 Android 上可用的第三方 RN 库在 OpenHarmony 上不一定能用——因为那些库如果涉及原生代码必须要有对应的 OpenHarmony 原生实现没有就是不能用。2.2 为什么适配套件要选 ArkTS 那一侧做原生能力另一个值得记录的底层结论是RNOH 的原生端是基于 ArkTS 和 ArkUI 能力去对接 JS 侧的而非重新实现一套 UI 引擎。这意味着两件事。第一你在 OpenHarmony 上通过 React Native 开发的页面最终渲染性能的上限取决于 ArkUI 组件的能力并非完全取决于 RN 的 Diff 算法有多快。第二当你需要补一些 RN 组件覆盖不到的原生能力时比如读取设备唯一标识、调用震动马达、打开系统设置页等你不再需要像 Android 那样写 Java/Kotlin而是用 ArkTS 写一个原生模块向 JS 侧暴露接口。对于一位有 Android 原生背景的人这套思路几乎毫无迁移成本对于纯 RN 前端的同学反而需要补充一点点 ArkTS 的基础知识但难度不大。那天现场有位 A 同学问了一个很典型的问题如果我在 OH 平台用 RN 写页面到底算不算是鸿蒙原生开发导师给了一个很贴切的类比你在 Linux 上用 JVM 跑 Java算不算 Linux 原生开发算一半。应用跑在原生的操作系统上但运行时是 JVM最后二进制不是 ELF 可执行文件而是 HAP 包。类似地RNOH 工程最终打出来的是 OpenHarmony 的 HAP 包可以上架到对应应用市场但在应用内部你的核心业务仍然是 JS 逻辑加原生壳这就是跨平台方案的位置。3. 环境准备把 RN 开发栈整体搬到 OH 生态3.1 需要安装的组件以及一个常见误区DAY 1 装过一遍环境之后DAY 2 的训练营默认所有人都已经有了基础的 OpenHarmony 开发环境但实际上到了现场才发现真正把 RNOH 跑通的人只占一半。剩下的同学大多卡在一个地方把 React Native 的调试器依赖装到了系统全局而 RNOH 模板工程要求的是项目内安装指定版本的依赖。这里我先把环境清单完整列出来供参考组件用途版本建议Node.js跑 React Native 的脚手架和 Metro 打包器建议 18 及以上DevEco StudioOpenHarmony 应用开发 IDE、编译打包使用训练营指定版本OpenHarmony SDK 和 toolchains编译、签名、生成 HAP 包跟随 DevEco Studio 自动下载ohpmOpenHarmony 的包管理器类似 Maven 和 npm 的结合体跟随 SDK 一起RN 适配层脚手架生成同时包含 RN 侧和 OH 原生侧的双端工程使用 npm 安装社区适配脚手架这里最容易踩的坑是记不清“RSM”这个角色。简单说RNOH 工程里有两套包管理体系一套是 JS 侧的 npm负责管理 React、React Native、Babel 编译插件这些前端依赖另一套是 OpenHarmony 侧的 ohpm负责管理 ArkTS 侧的原生组件和底层适配包。两边的包不是同一个东西npm install 装不到 ArkTS 侧ohpm install 也装不到 JS 侧必须分别在两个目录下执行各自的安装命令。实际操作里脚手架一般会生成两层目录结构外层是 OpenHarmony 的工程目录内层有一个 rn 子目录专门放 JS 代码和相关配置。构建流程也是两段式先把 JS 代码打包成一个 bundle 文件再把这个 bundle 作为资源放进 OpenHarmony 工程里统一编译。第一次跑通的时候你会在 DevEco Studio 的编译日志里同时看到 hvigor 和 Metro 的输出不用慌这是正常的。3.2 工程初始化三段式命令背后的逻辑训练营上导师演示了一次完整初始化。核心命令大致可以归纳为三段使用脚手架创建一个空模板工程里面包含 OpenHarmony 原生壳和 rn 子目录。进入 rn 目录npm install 安装 JS 侧依赖。回到外层目录执行 ohpm install 安装原生侧依赖。这三步的顺序不能乱。如果先执行 ohpm install原生侧会去尝试关联 JS 侧的资源文件而这时候 你的 node_modules 还不存在构建必然失败。反过来npm install 会在 postinstall 阶段做一次原生侧的配置校验这一阶段也会提前暴露出依赖不匹配的问题。还有一个细节值得提一下模板工程默认会把 React Native 基线版本写死在 package.json 里不同模板对应的 RN 版本基线不一样建议优先选用训练营或者社区 README 里明确标注的版本不要手痒升级到最新版本。因为 RNOH 的适配层是紧跟特定 RN 版本做的跨版本升级容易遇到组件映射缺位的问题后面排错非常痛苦。4. 组件和 API 的真实映射别被“兼容”两个字骗了4.1 哪些基础组件直接可用用一个平时开发中很常见的页面来验证顶部一个搜索框中间一个列表列表项里有图片、文本、一个按钮。我在训练营的模拟项目 X 里用标准的 RN 组件把整个页面写完测试结果如下RN 组件在 OpenHarmony 上的表现备注View直接映射为 ArkUI 的容器组件布局行为基本一致Flex 布局可用Text直接映射为 ArkUI 的 Text基础样式可用部分字体默认值有差异TextInput基础输入可用但光标样式、自动聚焦行为的细节需要适配个别 API 参数无效Image支持网络图和本地资源图加载逻辑与 Android 基本一致需要注意缓存策略ScrollView可用滚动性能在长列表场景一般建议长列表改用 FlatListFlatList可用支持滚动、下拉刷新方案的接入性能强于 ScrollViewTouchableOpacity / Pressable可用点击反馈正常部分场景点击区域计算有差异Modal基础弹窗可用遮罩层透明度等细节和 Web 端行为不一样注意测真机SafeAreaView部分场景不工作建议自己写安全区适配Alert可用但弹窗按钮顺序与 Android 存在差异最好二次封装StatusBar有差异部分返回值在真机上不准谨慎依赖这些结论是我拿模拟项目 X 逐个跑出来的不是纸面推断。里面最需要警惕的是“可用但不完全一致”的那一组TextInput、SafeAreaView、StatusBar。这类组件在你的业务里一旦用上了就很可能成为测试阶段的隐藏炸弹。4.2 Platform 判断和 Dimensions 的坑跨平台开发中代码里经常会出现 Platform.OS 这个判断在 RNOH 上Platform.OS 返回的值是 ohos这一点直接让很多第三方组件库的兼容分支失效。你安装一个依赖了 react-native 内部模块的第三方库时如果对方只在代码里判断了 android 和 ios那它在 OH 平台上很可能走的是默认分支甚至直接崩溃。Dimensions.get 也有类似问题。OpenHarmony 上窗口的分辨率、状态栏高度都和 Android 侧不完全一致。训练营现场有个同学写了一个获取状态栏高度来调整页面 padding 的逻辑在 Android 上正常换到 OpenHarmony 上明显偏大了最后拿到真机截图比对才发现是 Dimensions 返回的数值没包含真实状态栏高度。我的建议是在 RNOH 项目里把这类系统相关的取值统一封装成一个独立的工具函数不要散落在业务代码里。以后底层适配层更新了你只需要改一个文件就能完成全量修正不然每个页面去排查会非常痛苦。4.3 导航和网络请求的处理导航方案方面训练营验证了当前使用相对广泛的 React Navigation 在 RNOH 上可以跑通基础导航建议直接在 template 里使用它的原生栈模式。但要注意React Navigation 内部依赖了 react-native-screens 这个库而它又需要原生侧的对应实现所以一定要确认你安装的版本和 RNOH 适配层是配套的否则页面跳转时会黑屏或卡住。网络请求就好很多。因为 RN 侧用的依然是 fetch 或者 axios底层走的还是标准的网络协议栈基本上 Android 上能发什么请求在 OH 上也能发。真正的差异在权限OpenHarmony 应用的网络权限、数据访问权限需要在 module.json5 里显式声明不像调试模式下自动放行。第一天主要注意网络权限后续如果要碰相机、存储、地理位置统统要在这里加权限描述少一项就功能失效。5. “模拟项目 X”从列表到详情的完整 Demo5.1 页面设计和数据链路设计训练营下午的整块时间都在做一个名称为“模拟项目 X”的实际项目它的业务逻辑很简单一个商品浏览应用包含首页商品列表、搜索框、商品详情页、收藏列表四个主要页面。这个项目的意义不在于业务复杂度而在于它在最小范围内覆盖了 RNOH 开发中最核心的几条链路列表数据从网络接口加载并做分页。列表项点击后通过导航传参进入详情页。搜索框输入文字后触发列表过滤。收藏操作通过本地存储持久化。我特别想把数据链路这一步讲清楚。在 RNOH 项目里你的 JS 代码照常运行网络请求、状态管理Redux 或 Zustand、业务逻辑都不受影响真正的分界点只在 UI 组件渲染和原生能力调用这两头。所以你在设计 Demo 时可以完全沿用原来的三层结构页面组件层、状态管理层、数据服务层这套结构在 OpenHarmony 上依然成立。5.2 首页列表的实现要点与 FlatList 优化写首页列表时我直接用了 FlatList这比 ScrollView 加 map 的方式性能好很多。原因是 FlatList 内部会做窗口化渲染屏幕外的列表项会被回收。在 RNOH 上这个机制依然生效所以在长列表场景优先选它别偷懒。关键写法有几处给 FlatList 设置 keyExtractor确保每一条数据都有稳定且唯一的 key。如果列表项高度固定建议提供 getItemLayout这样可以显著减少布局计算成本。避免在 renderItem 内部内联定义函数每一次滚动都会触发重新渲染。训练营还分享了一个在 OpenHarmony 上特别值得注意的性能问题图片加载。列表里有大量网络图片时图片的缓存策略对滚动的流畅度影响极大因为适配层默认不一定开启了合理的磁盘缓存。建议在 image 组件层面配置好缓存策略或者把图片缩略图尺寸在上游服务端压缩列表项里的图片不要直接用原图。5.3 导航传参、搜索防抖和收藏持久化详情页的导航传参没有太多意外React Navigation 的标准用法可以直接跑通。但训练营强调了一个细节传参最好只传 id 或轻量对象不要把整个列表项对象完整传过去。原因是有时候你在列表页更新了数据但详情页拿到的还是旧的快照容易踩到数据一致性的坑。传 id 之后详情页自己再拉一次数据逻辑反而更干净。搜索框的防抖逻辑我用了常规的 setTimeout 方案。这里要特别留意一个 OH 平台上的差异TextInput 的 onChangeText 触发频率在某些输入法下会明显偏低或变高如果业务对实时搜索要求高最好自己加一层输入缓冲同时结合 controlled 组件管理 value别完全依赖原生事件。收藏数据持久化我试了社区常用的 AsyncStorage 适配实现在小数据量场景足够用。如果是生产项目建议直接用它背后的 SQLite 存储做封装或者走 OpenHarmony 侧提供的轻量数据库总之不要在 AsyncStorage 里塞大对象。6. 原生桥接用 ArkTS 给 RN 补上原生能力6.1 什么时候需要写原生态桥接RNOH 的适配层虽然组件和 API 覆盖面不小但和平台强相关的系统能力还是得靠原生态拟合。模拟项目 X 做到最后一步我需要在收藏时触发一次震动反馈。这个需求用 RN 自带的 API 在 OH 上是空的必须自己补。写原生模块的思路和 Android/iOS 一样先在 ArkTS 侧实现功能再向 JS 暴露一个模块最后在 JS 里直接 require 或 import。具体要做的三件事是在 OpenHarmony 原生工程中创建一个 ArkTS 类继承自适配层规定的基类并实现一个方法。把该类注册到模块列表中让它能在启动时被 JS 侧找到。在 JS 侧封装一个工具函数调用该模块的方法。6.2 一个震动模块的真实实现草稿ArkTS 侧的核心代码大致是下面这个样子import { Vibration } from ohos.vibrate; import { RNOHEmitter } from react-native-openharmony; export class VibrationModule extends RNOHEmitter { vibrate(duration: number): void { Vibration.startVibration({ type: time, duration: duration, id: 0 }).catch((error) { console.error(vibrate failed, JSON.stringify(error)); }); } cancel(): void { Vibration.stopVibration(); } }JS 侧的调用封装长这样import { NativeModules } from react-native; const { VibrationModule } NativeModules; export const hapticFeedback (duration 200) { VibrationModule.vibrate(duration); }; export const cancelHaptic () { VibrationModule.cancel(); };这段代码不是能直接复制的线上版本但结构上就把三要素说透了原生类、接口方法、JS 封装。实际写的时候不同适配层的注册方式会略有区别所以具体以你安装的适配层文档为准。这里有一个特别常见的坑新写的原生模块在 JS 侧一直显示 undefined。训练营现场排查了好几个同学的例子最终定位出来原因几乎都是一个——原生侧没有在配置里把模块注册进来或者注册顺序不对导致 JS 端找不到。这个问题和 Android 开发早期写 RN 原生模块时忘了在包管理器里注册一模一样。调试这类问题时最快的判断方法是看 DevEco Studio 的日志。如果 JS 侧调用 NativeModules 时能拿到对象说明注册成功拿不到就去原生工程里检查注册代码不要反复去 JS 侧改代码。理清排查方向之后这个问题其实一小会儿就能解决。6.3 事件回调从原生向 JS 发消息除了 JS 主动调原生RNOH 同样支持原生端向 JS 侧发事件这在业务里也很有用。比如一个扫码模块原生扫描成功后才通知 JS 页面去更新界面。此时要用到 NativeEventEmitter 来订阅原生事件。基本原理是原生侧在合适时机发一个事件JS 侧预先注册监听。训练营给的建议是事件名要统一管理。可以定义一套常量文件把事件名集中维护千万不要散写在各个页面里。否则项目一大事件名拼错了排查成本极高。7. 真机部署、调试与性能分析的三板斧7.1 HAP 打包与真机安装的流程RNOH 开发的一个特殊之处是应用最终以 HAP 包的形式部署到 OpenHarmony 设备上。开发阶段有两种跑法一种是在 DevEco Studio 里直接运行调试模式它会启动 Metro 并同步 JS bundle另一种是打包成 HAP 安装到真机适合做整体性能验证和功能验收。打包之前需要先确认两件事签名配置有没有就绪这一点你可以在 DevEco Studio 里通过自动签名帮你生成配置还有 bundle 的构建是否已经执行。生产环境要求提前把 JS 代码打成 bundle 放到资源目录调试模式则允许 Metro 实时拉取代码两者的差异要心里有数。训练营上实际测试的结论是调试模式开发体验好但页面加载速度和列表滚动性能都明显不如 bundle 模式。所以做性能评估时一定要用打包后的安装包来测不能拿调试模式的数据作为最终参考。7.2 日志排查的三个技巧排查问题时的日志体系有多个出口JS 侧报错会出现在 Metro 输出里原生侧打印会出现在 DevEco Studio 的 HiLog 窗口还有一部分 ArkUI 渲染的错误藏在系统日志里。三处日志需要用关键词过滤否则会被无意义信息淹没。我的习惯是JS 侧问题先在 fetch 的网络请求里打印状态码和响应体。页面渲染问题去 HiLog 里搜 ReactNative 或者 ArkUI 关键词。原生模块未找到这类问题直接搜模块名。另外一个技巧在真机上遇到白屏十有八九是 bundle 没打进去或者签名不对。先排除环境问题再查代码问题这个顺序不要反。我之前就遇到过一回折腾许久发现是签名配置失效白白浪费很长时间。7.3 性能打点重点观察三个指标训练营在性能环节给出的评估框架很直接核心关注三个指标指标说明正常标准首屏渲染时间从启动到列表页出现内容和图片目标 2 秒以内滚动流畅度快速滑动列表时的掉帧情况无明显卡顿JS 线程阻塞主线程 JS 执行时间占比不应长期满负载如果发现首屏慢优先看是网络慢还是页面渲染慢。网络慢就去优化接口页面渲染慢就检查列表项复杂度。如果发现滚动掉帧优先检查 FlatList 的 renderItem 里有没有大图和复杂阴影效果。如果发现 JS 线程长期阻塞那就要看看是不是在动画里大量执行了复杂运算。性能优化的思路不要一上来就想什么大动作先把最基本的检查做完列表有没有窗口化渲染、图片有没有做尺寸压缩、页面有没有不必要的重复 render。RNOH 在自己的性能调优点上还没有 Android 生态那么多年积累能靠常规手段解决的先别急着上重武器。8. 那些坑帮你提前踩掉8.1 Alert 按钮顺序和 Modal 的展示位置训练营当天下午大家统一跑到同一个坑里Alert 在 OpenHarmony 上的按钮顺序竟然是反的Android 上是“确定、取消”在 OH 上变成了“取消、确定”。这种细节如果你不做真机测试根本发现不了。建议在项目里对 Alert 做一层封装由封装统一控制按钮顺序并把确认操作放在右侧。Modal 也有需要注意的地方它在某些版本上不是全屏盖住底部而是从底部弹起一个面板遮罩层的透明度也可以调节。这个行为和 Web 端差异不小如果你在业务里依赖 Modal 做全屏提示一定要先在真机上确认效果。8.2 图片缓存与生命周期问题Image 的缓存策略是另一个高频坑。默认行为在不同版本上可能不同有的情况下每次重新进入页面都会重新请求网络图这对列表性能和用户体验都有影响。建议排查一下适配层的默认缓存策略如果不符合预期可以在原生侧统一配置图片加载组件的缓存模式或者给图片 URL 加上合理的查询参数。页面生命周期方面useEffect 的清理逻辑也要注意。当页面从 A 跳转到 B 再返回时某些原生事件监听可能没有自动注销导致内存泄漏或者事件重复触发。这类问题在短时间反复切换页面时最容易暴露要养成在 useEffect 里 return 清理函数的习惯。8.3 字体、安全区和键盘弹起字体在 OH 上的默认字重和 Android 不完全一致。训练营里有个同学写了一个价格展示文本在 Android 上粗细正常在 OH 上明显偏细然后因为它依赖了自定义字体排查起来还很费劲。建议在做设计稿时把关键文本的字体粗细显式指定不要依赖系统默认。安全区适配也是老问题。某些页面的底部按钮在全面屏设备上会顶到系统手势条区域。建议不要依赖 SafeAreaView而是在页面最外层设置一个固定的底部内边距同时在页面收到 inset 变化时做一次实时调整。键盘弹起在 OH 上的表现也略有差异部分输入页面弹起键盘后会把整个页面顶上去而不是像 Android 那样触发 adjustResize 或 adjustPan。这个问题做聊天输入框或搜索框时最明显需要针对性地设置页面避让方式。9. 我的个人结论和下一步想做的事从 DAY 2 下来我对 RNOH 的定位从“一个能跑通的实验项目”变成了“一条可以认真评估的跨端路径”。这话不是客套而是基于一整天的实际操作判断的。一个团队如果已经有成熟的 RN 跨端产品那将代码迁移到 OpenHarmony 的成本主要会花在四个地方组件兼容性的逐个验证、原生模块的补全、真机适配的细节打磨、性能的专项优化。这些工作没有特别大的技术风险核心是耐心和细致。对于纯前端背景、没有原生开发经验的开发者我的建议是先把 ArkTS 基础语法补上不要求你写出多复杂的原生实现但至少能看懂原生模块的注册和导出过程。因为 RNOH 项目一旦进入原生能力扩展阶段你会发现前后端两侧的配合是这个框架真正的分水岭。我接下来的计划是先做三个小验证第一个是给模拟项目 X 增加简单的地理位置读取看看定位模块的桥接成熟度第二个是测试一套自定义字体在 OH 端的渲染效果第三个是跑一个稍重度的列表页面对比不同列表方案在真机上的滚动帧率。等这些结果出来我大概率会把迁移评估写成一份偏工程层面的决策文档而不是停留在技术体验的层面。这次训练营让我想起一个老生常谈但每次都能被验证的结论跨平台框架的价值从来不在于“一次编写、处处完美”而在于“一次学习、处处能用”。在 OpenHarmony 生态逐渐成熟的加速期把 React Native 的能力映射到这块新的土壤是一件值得动手去做的事。希望这篇笔记能帮你少踩几个坑也欢迎有实际迁移经验的朋友一起交流那些我在文中还停留在“建议验证”层面的问题。
