【开源鸿蒙跨平台开发先锋训练营】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 下载与配置

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

1.3 环境变量配置 (关键)

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

JAVA_HOME : 指向 JDK 17 安装目录 (例如 C:\Program Files\Java\jdk-17).
OHOS_SDK_HOME : 指向 DevEco SDK 安装目录 (例如 C:\Users\YourUser\AppData\Local\OpenHarmony\Sdk).
HDC_HOME (可选): 指向 toolchains 目录 %OHOS_SDK_HOME%\10\toolchains.
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 仓库

登录 AtomGit。
点击右上角 "+" -> "新建仓库"。
填写仓库信息：
- 仓库名称 : rnoh-cross-platform-demo (示例)
- 描述: React Native for OpenHarmony 跨平台开发实战项目
- 公开性 : 选择公开
- 初始化: 勾选 "添加 README.md", ".gitignore" (选择 Node 或 C++ 模板), "开源许可证" (推荐 Apache-2.0 或 MIT)。
创建完成后，复制 HTTPS 或 SSH 克隆地址。

2.2 本地 Git 初始化与配置

在本地工作区执行：

bash 复制代码

# 全局配置用户签名
git config --global user.name "YourName"
git config --global user.email "your.email@example.com"

# 克隆仓库
git clone https://atomgit.com/YourUsername/rnoh-cross-platform-demo.git
cd rnoh-cross-platform-demo

2.3 分支管理规范

main: 主分支，存放稳定版本代码。
dev: 开发分支，日常开发使用。
feature/xxx: 功能分支，开发特定功能时从 dev 切出。

bash 复制代码

# 创建并切换到开发分支
git checkout -b dev

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

3.1 创建 RNOH 工程

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

bash 复制代码

# 1. 初始化标准 RN 项目 (版本需参考 RNOH 官方推荐，如 0.72.5)
npx react-native@0.72.5 init MyRNOHApp

# 2. 进入项目并安装鸿蒙适配依赖
cd MyRNOHApp
npm install @rnoh/react-native-openharmony

# 3. 补全鸿蒙工程结构 (参考 RNOH 官方文档或模板)
# 通常需要将 sample 中的 harmony 文件夹复制到项目根目录
# 并修改 harmony/build-profile.json5 中的签名配置

3.2 工程配置与依赖

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

3.3 编译与运行

确保 Metro 服务已启动：

bash 复制代码

npm start

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

使用 DevEco Studio 打开 harmony 目录：

等待 Sync 完成。
在右上角选择运行设备（模拟器或真机）。
点击 Run 'entry' (绿色三角形)。

场景 B: 命令行运行 (进阶)

bash 复制代码

# 确保 hdc 连接正常
cd harmony
./hvigorw.bat assembleHap --mode debug
hdc install entry/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 包含以下内容，避免提交临时文件：

text 复制代码

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

4.2 提交代码

bash 复制代码

# 1. 添加文件
git add .

# 2. 提交 (使用清晰的 Commit Message)
git commit -m "feat: 完成RNOH工程初始化及多端运行适配"
# 格式建议: type(scope): subject
# type: feat(新功能), fix(修补), docs(文档), chore(构建/依赖)

# 3. 推送到远程 dev 分支
git push origin dev

4.3 合并到主分支 (Release)

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

bash 复制代码

git checkout main
git merge dev
git push origin main

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

5.1 Metro 连接问题

现象 : App 启动后一直显示 "Connecting to Metro..." 或白屏。
原因 : 真机/模拟器无法访问电脑端的 8081 端口。
解决 :

必须使用 hdc 进行端口转发：

bash 复制代码

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

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

一、 开发环境搭建

1.1 前置软件安装

1.2 OpenHarmony SDK 下载与配置

1.3 环境变量配置 (关键)

1.4 多设备调试驱动

二、 Git 与 AtomGit 仓库操作

2.1 创建 AtomGit 仓库

2.2 本地 Git 初始化与配置

2.3 分支管理规范

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

3.1 创建 RNOH 工程

3.2 工程配置与依赖

3.3 编译与运行

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

场景 B: 命令行运行 (进阶)

3.4 运行日志与证据

四、 代码提交规范

4.1 清理与忽略

4.2 提交代码

4.3 合并到主分支 (Release)

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

5.1 Metro 连接问题

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

5.3 签名失败

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

6.1 架构视角的转变

6.2 版本"强绑定"

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

七、 生态资源

一、开发环境搭建

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

四、代码提交规范

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

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

七、生态资源