本笔记详细记录了在 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 初始化与配置
在本地工作区执行：
# 全局配置用户签名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-demo2.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 工程配置与依赖
- Local Properties: 在
harmony/local.properties中指定 SDK 路径：sdk.dir=C:/Users/YourUser/AppData/Local/OpenHarmony/Sdk - 权限声明: 在
harmony/entry/src/main/module.json5中添加网络权限等："requestPermissions":[{"name":"ohos.permission.INTERNET"}]
3.3 编译与运行
确保 Metro 服务已启动：
npmstart场景 A: 模拟器/真机运行
使用 DevEco Studio 打开harmony目录：
- 等待 Sync 完成。
- 在右上角选择运行设备（模拟器或真机）。
- 点击Run ‘entry’(绿色三角形)。
场景 B: 命令行运行 (进阶)
# 确保 hdc 连接正常cdharmony ./hvigorw.bat assembleHap --mode debug hdcinstallentry/build/default/outputs/default/entry-default-signed.hap3.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.properties4.2 提交代码
# 1. 添加文件gitadd.# 2. 提交 (使用清晰的 Commit Message)gitcommit -m"feat: 完成RNOH工程初始化及多端运行适配"# 格式建议: type(scope): subject# type: feat(新功能), fix(修补), docs(文档), chore(构建/依赖)# 3. 推送到远程 dev 分支gitpush origin dev4.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
