news 2026/5/3 16:00:34

【开源鸿蒙跨平台开发先锋训练营】DAY 2 React Native for OpenHarmony 开发笔记与实战指南

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
【开源鸿蒙跨平台开发先锋训练营】DAY 2 React Native for OpenHarmony 开发笔记与实战指南

本笔记详细记录了在 Windows 11 环境下搭建 React Native for OpenHarmony (RNOH) 开发环境、创建多终端工程、以及代码提交至 AtomGit 的全流程。

一、 开发环境搭建

1.1 前置软件安装

在开始配置 OpenHarmony 特有环境前，需完成以下基础软件的安装（参考已验证的教程）：

  • VS Code: 代码编辑器 安装指南
  • Git: 版本控制工具 安装指南
  • Java (JDK 17): 必须安装 JDK 17，RNOH 依赖此版本 安装指南
  • Android Studio: 用于管理通用移动端依赖（可选，建议安装） 安装指南
  • DevEco Studio: 鸿蒙应用开发核心 IDE 安装指南

完成安装后启动运行界面如下：

系统提供了很多模板，在文件-新建项目下，可以非常方便的新建项目。

1.2 OpenHarmony SDK 下载与配置

  1. 打开DevEco Studio，进入Settings>SDK。
  2. 勾选并下载API 10 (或更高版本)的 SDK。确保同时下载了OpenHarmony SDK和HarmonyOS SDK（视具体目标设备而定）。
  3. 在 SDK Tools 标签页中，勾选安装：
    • Native(C++ 工具链)
    • CMake
    • Command Line Tools(hdc 工具在此包含)

1.3 环境变量配置 (关键)

为了支持 React Native 的 C++ 编译和命令行工具，需配置系统环境变量：

  1. JAVA_HOME: 指向 JDK 17 安装目录 (例如C:\Program Files\Java\jdk-17).
  2. OHOS_SDK_HOME: 指向 DevEco SDK 安装目录 (例如C:\Users\YourUser\AppData\Local\OpenHarmony\Sdk).
  3. HDC_HOME(可选): 指向 toolchains 目录%OHOS_SDK_HOME%\10\toolchains.
  4. Path: 添加以下路径到系统 Path 变量中：
    • %JAVA_HOME%\bin
    • %OHOS_SDK_HOME%\10\toolchains(用于 hdc 命令)
    • %OHOS_SDK_HOME%\10\native\build-tools\cmake\bin(用于 cmake 编译)

验证: 打开 PowerShell 输入hdc -v和cmake -version，应能正确输出版本号。

1.4 多设备调试驱动

  • 真机 (Phone/Pad): 开启开发者模式 -> USB 调试。连接电脑后，使用hdc list targets查看设备 ID。
  • 模拟器: 在 DevEco Studio > Device Manager 中创建 API 10+ 的模拟器并启动。
  • 开发板 (如 DAYU200): 通过 USB 连接，确保安装了相应的 USB 串口驱动。

我们在开发过程中需要经常用到模拟器，所以一定要学会模拟器的安装方法。选中Device Manager 根据本机配置创建。


在如下界面创建新机并选择合适的配置。

二、 Git 与 AtomGit 仓库操作

2.1 创建 AtomGit 仓库

  1. 登录 AtomGit。

  2. 点击右上角 “+” -> “新建仓库”。

  3. 填写仓库信息：

    • 仓库名称:rnoh-cross-platform-demo(示例)
    • 描述: React Native for OpenHarmony 跨平台开发实战项目
    • 公开性: 选择公开
    • 初始化: 勾选 “添加 README.md”, “.gitignore” (选择 Node 或 C++ 模板), “开源许可证” (推荐 Apache-2.0 或 MIT)。

  4. 创建完成后，复制 HTTPS 或 SSH 克隆地址。

2.2 本地 Git 初始化与配置

在本地工作区执行：

# 全局配置用户签名gitconfig --global user.name"YourName"gitconfig --global user.email"your.email@example.com"# 克隆仓库gitclone https://atomgit.com/YourUsername/rnoh-cross-platform-demo.gitcdrnoh-cross-platform-demo

2.3 分支管理规范

  • main: 主分支，存放稳定版本代码。
  • dev: 开发分支，日常开发使用。
  • feature/xxx: 功能分支，开发特定功能时从 dev 切出。
# 创建并切换到开发分支gitcheckout -b dev

三、 工程创建与多终端运行验证

3.1 创建 RNOH 工程

使用 React Native 官方 CLI 结合 RNOH 模板创建项目：

# 1. 初始化标准 RN 项目 (版本需参考 RNOH 官方推荐，如 0.72.5)npx react-native@0.72.5 init MyRNOHApp# 2. 进入项目并安装鸿蒙适配依赖cdMyRNOHAppnpminstall@rnoh/react-native-openharmony# 3. 补全鸿蒙工程结构 (参考 RNOH 官方文档或模板)# 通常需要将 sample 中的 harmony 文件夹复制到项目根目录# 并修改 harmony/build-profile.json5 中的签名配置

3.2 工程配置与依赖

  1. Local Properties: 在harmony/local.properties中指定 SDK 路径：
    sdk.dir=C:/Users/YourUser/AppData/Local/OpenHarmony/Sdk
  2. 权限声明: 在harmony/entry/src/main/module.json5中添加网络权限等：
    "requestPermissions":[{"name":"ohos.permission.INTERNET"}]

3.3 编译与运行

确保 Metro 服务已启动：

npmstart
场景 A: 模拟器/真机运行

使用 DevEco Studio 打开harmony目录：

  1. 等待 Sync 完成。
  2. 在右上角选择运行设备（模拟器或真机）。
  3. 点击Run ‘entry’(绿色三角形)。
场景 B: 命令行运行 (进阶)
# 确保 hdc 连接正常cdharmony ./hvigorw.bat assembleHap --mode debug hdcinstallentry/build/default/outputs/default/entry-default-signed.hap

3.4 运行日志与证据

  • 日志查看: 在 DevEco Studio 底部Log窗口，或使用命令hdc hilog。
  • 截图保存: 运行成功后，截取模拟器/真机画面，保存为run_evidence_emulator.png或run_evidence_device.png放入docs目录。

四、 代码提交规范

完成开发验证后，将代码推送到 AtomGit。

4.1 清理与忽略

确保.gitignore包含以下内容，避免提交临时文件：

node_modules/ .idea/ .vscode/ android/app/build/ ios/Pods/ harmony/entry/build/ harmony/.hvigor/ *.hap local.properties

4.2 提交代码

# 1. 添加文件gitadd.# 2. 提交 (使用清晰的 Commit Message)gitcommit -m"feat: 完成RNOH工程初始化及多端运行适配"# 格式建议: type(scope): subject# type: feat(新功能), fix(修补), docs(文档), chore(构建/依赖)# 3. 推送到远程 dev 分支gitpush origin dev

4.3 合并到主分支 (Release)

在 AtomGit 平台发起 Pull Request，或在本地合并：

gitcheckout maingitmerge devgitpush origin main

五、 常见问题与避坑指南 (Troubleshooting)

5.1 Metro 连接问题

现象: App 启动后一直显示 “Connecting to Metro…” 或白屏。
原因: 真机/模拟器无法访问电脑端的 8081 端口。
解决:
必须使用 hdc 进行端口转发：

hdc rport tcp:8081 tcp:8081
  • 确保电脑和手机在同一 Wi-Fi 下（如果是无线调试）。
  • 检查harmony/entry/src/main/resources/rawfile/rn_config.json中的bundleUrl是否正确指向了电脑 IP。

5.2 C++ 编译报错 (CMake Error)

现象: Sync 或 Build 时报错CMake Error: ...或Ninja not found。
原因: 环境变量未生效或 SDK 路径配置错误。
解决:

  • 检查local.properties中的路径分隔符是否为/(Windows 下不要用单反斜杠\)。
  • 确保cmake命令在终端可直接执行。
  • 如果使用 DevEco Studio 4.0+，建议清理.hvigor和build目录后重试。

5.3 签名失败

现象: 安装 HAP 时提示INSTALL_FAILED_VERIFY_APP_PKCS7_FAIL。
解决:

  • 必须在 DevEco Studio 中配置自动签名 (Project Structure > Signing Configs > Automatically generate signature)。
  • 如果是真机，需要确保设备 UDID 已添加到签名文件中。

六、 开发感悟与经验总结 (Insights)

6.1 架构视角的转变

与 Android/iOS 的 React Native 不同，RNOH 采用了更激进的C-API 架构。这意味着 JavaScript 代码直接通过 N-API 与 C++ 层交互，最后通过 ArkUI 的 XComponent 进行渲染。

  • 优势: 理论上性能上限更高，因为绕过了部分 Java/JS Bridge 的开销。
  • 挑战: 对 C++ 环境依赖更重，初次配置比 Android 复杂，需要开发者对 Native 编译流程有一定了解。

6.2 版本“强绑定”

RNOH 目前处于快速迭代期，版本兼容性极为敏感：

  • RN 版本: 必须严格使用 RNOH 官方文档指定的 React Native 版本（如0.72.5），不要随意升级到最新版。
  • API 版本: OpenHarmony API 10 和 API 11 的底层接口差异较大，务必确认 SDK 版本与 RNOH 版本的对应关系。

6.3 跨平台开发的“最后一公里”

虽然 React Native 实现了“一次编写，到处运行”，但在鸿蒙平台上，目前仍需手动处理不少“最后一公里”的工作：

  • 第三方库的适配（如相机、地图）往往需要寻找对应的ohos适配版本或自己实现 TurboModule。
  • 因此，不仅要懂 React，还要适当补充 ArkTS 和 C++ 的知识，这将是未来鸿蒙跨端开发者的核心竞争力。

七、 生态资源

  • RNOH 核心仓库: react-native-openharmony
  • 三方库适配列表: RNOH 三方库列表
  • 官方文档: RNOH 文档中心

欢迎加入开源鸿蒙跨平台社区：
https://openharmonycrossplatform.csdn.net

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/22 14:42:05

C4D + Corona 渲染玻璃材质详解：Thin Shell 与实心玻璃的正确使用方式

原创声明本文为原创技术整理文章，内容基于 Corona Renderer 在 Cinema 4D 中的实际使用经验总结，转载请注明出处。一、前言在 Cinema 4D 的实际项目中，玻璃材质是建筑可视化、室内渲染及产品渲染中非常常见的一类材质。 在 Corona Renderer 中…

作者头像 李华
网站建设 2026/4/30 1:32:59

自动驾驶测试事故：模拟与现实的系统性鸿沟及测试范式革新

一、导言：血淋淋的警示碑 2025年特斯拉Model S在暴雨中误识别白色货柜车为天空导致的致命撞击，2026年Waymo车辆在旧金山浓雾中无视临时施工路标的集体违规——这些事故揭开了自动驾驶行业最严峻的挑战：测试环境与真实世界的认知断层。作为软…

作者头像 李华
网站建设 2026/5/3 11:28:43

‌古文明密码测试：用AI破译玛雅历法的漏洞‌

当测试思维遇见千年碑文 在帕伦克遗址斑驳的石碑前，AI算法正在执行一场跨越两千年的特殊测试任务。玛雅历法系统作为人类最早的复杂时间计算体系之一，其长计历（Long Count）模块曾因2012末日预言引发全球误读。本文将以软件测试工…

作者头像 李华
网站建设 2026/5/3 8:59:53

esp32，使用esp-idf链接mqtt服务器，消息接收

本次连接使用的是mqtt的官方公共服务器，前提是要先链接wifi注意：1.mqtt服务器发给esp32的消息，中间没有/0,使用“%s”这种格式打印的数据会自动往后打印，直到遇见/0,解决方法是ESP_LOGI(TAG_MQTT,"topic->%.*s",mqtt…

作者头像 李华
网站建设 2026/5/2 14:14:55

高通CEO安蒙播客访谈：移动DNA也能做好数据中心

作者：周雅 2026年1月12日，HUMAIN出品的首档播客《End of Limits》第一期邀请到了一位特别嘉宾：高通公司总裁兼CEO安蒙（Cristiano Amon）。这场对话始于当下最炙手可热的AI，一路探向边缘计算、下一代设备革命…

作者头像 李华