1. 为什么我会在 0 基础时直接选 React Native 做鸿蒙开发
先交代一下背景:我是从 Android 原生转到跨平台方向的,之前完全没写过 React Native,也没正经接触过鸿蒙应用开发。之所以敢直接上手“React Native 鸿蒙跨平台开发”这个方向,是因为我盯上了两个刚需场景——一是 App 启动时白屏时间太长,二是团队需要一套代码同时覆盖 Android、iOS 和鸿蒙。
这里先解释一个关键认知:React Native 能跑在鸿蒙上,并不是华为官方直接内置了 RN 支持,而是因为开源社区和厂商合作推动的 React Native for OpenHarmony 适配层。也就是说,你写的 JS 业务逻辑可以跨平台复用,但最终要落到鸿蒙的 ArkUI 组件树上,中间需要一套桥接实现。这个适配层目前已经能覆盖大部分核心组件和 API,但对于新手来说,最直观的感受就是:启动白屏的问题比纯 WebView 方案轻得多,又比纯原生开发省人力。
我踩过的第一个坑就是以为“React Native 鸿蒙开发”和普通 RN 开发完全一样,实际上编译目标、依赖版本、原生工程结构都需要按鸿蒙的规则来。如果你也是 0 基础,我强烈建议先理解清楚这条技术链:JS 代码 → RN 运行时 → 鸿蒙桥接层 → ArkUI 渲染。骨架屏 Skeleton 刚好是切入这个链路的最佳练习项目,因为它在业务上不复杂,但能逼你把 RN 组件如何映射到鸿蒙、样式如何生效、加载态如何管理都摸一遍。
适合看这篇文章的人,我觉得有三类:
- 完全没接触过 RN 和鸿蒙开发,但想快速跑通一个跨平台 Demo 的新手;
- 已经有 RN 开发经验,想迁移到鸿蒙平台,同时优化启动体验的开发者;
- 团队正在评估跨平台方案,想知道骨架屏这类 UI 细节在鸿蒙上能不能落地的人。
说白了,本文不是把官方文档念一遍,而是把我从环境搭建到骨架屏实现、再到鸿蒙适配踩坑的完整过程写出来,让你能少走弯路。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与 React Native 鸿蒙工程初始化
2.1 你需要装哪些东西
别一上来就盯着鸿蒙 DevEco Studio 猛装,先把 RN 侧的环境搞定。我实际用到的环境版本如下,不同版本坑的位置不一样,建议尽量对齐:
- Node.js:18 或 20 LTS 版本,我用的 20.11.1,太老的版本会导致新版 RN CLI 跑不起来;
- JDK:17,鸿蒙工程编译对 JDK 版本有要求,11 或 8 都可能报 Gradle 兼容问题;
- DevEco Studio:5.0 及以上版本,用来打开鸿蒙原生工程;
- React Native:0.72 或 0.73 版本,目前鸿蒙适配层对这两个版本支持最好;
- OpenHarmony SDK:建议用 API 10 或更高版本,太低的话部分 RN 组件映射不了。
还有一个容易被忽略的点:你需要装好 HarmonyOS/OpenHarmony 的命令行工具,并确认 hdc 命令可用,否则后面连接模拟器或真机调试会卡住。我一开始就漏了 hdc,导致跑 react-native run-harmony 的时候一直提示找不到设备。
2.2 初始化 RN 工程并接入鸿蒙适配层
直接按普通 RN 方式初始化项目:
bash复制npx react-native init RnHarmonySkeleton --version 0.73.2
这一条命令会生成一个标准的 RN 工程。接下来要接入鸿蒙适配层,目前国内社区主要用的是 React Native for OpenHarmony 的镜像和脚手架。以我用的方案为例,你需要把鸿蒙工程目录生成到 harmony 文件夹下,然后在 harmony 目录里执行鸿蒙侧的依赖安装。
这里我不建议新手直接手动改原生工程,因为 ArkTS 和 ArkUI 的工程结构对没接触过的人来说会非常绕。更稳的方式是使用社区提供的初始化脚本,它会自动完成以下工作:
- 在
harmony目录生成 OpenHarmony 工程; - 配置好 RN 依赖的
react_native_openharmony包; - 把 RN 的 bundle 加载逻辑接入 ArkUI 的
RNInstance生命周期。
等脚本跑完,整个工程会同时包含 android、ios 和 harmony 三个目录。看到 harmony 目录出现时,说明工程已经具备跨三个平台的结构了。
2.3 鸿蒙侧 dev 模式的启动流程
很多新手以为鸿蒙跟 Android 一样,直接 npm start 就能跑起来,实际上鸿蒙侧的加载流程要稍微绕一下。你需要先在 DevEco Studio 里打开 harmony 目录,等 Gradle 同步完成,然后连接鸿蒙模拟器或真机。启动 Metro 服务:
bash复制npm start
然后在 DevEco Studio 里点击运行,App 会启动并尝试从 Metro 拉取 JS bundle。如果一切正常,你会看到骨架屏和业务界面都能正常渲染。
我遇到的一个高频报错是 bundle 加载超时,这是因为鸿蒙模拟器默认网络环境和 Metro 的访问地址没配好。解决办法是在 DevEco Studio 的运行配置里,把 Metro 地址改成你电脑的局域网 IP,而不是默认的 localhost。这个坑在后文常见问题里会展开讲。
3. 骨架屏 Skeleton 在 React Native 中的实现思路
3.1 为什么骨架屏能解决白屏问题
原生 RN 应用在启动时,需要经历“加载 JS Bundle → 解析并执行 JS → 渲染原生组件”这几个阶段。如果 bundle 体积大或设备性能一般,用户会看到一段没有内容的纯白
