一篇文档轻松玩转 RNOH Debug / Release 包使用

ReactNativeOH

2人浏览 · 2026-05-22 15:35:28

ReactNativeOH · 2026-05-22 15:35:28 发布

本指南面向鸿蒙工程中 RNOH（React Native for OpenHarmony）原生模块的集成与构建，涵盖 Debug 包和 Release 包两种构建方式的使用。

前提：开发者已按照环境搭建完成环境配置，已有一个可正常运行的鸿蒙工程框架（包含 EntryAbility.ets、RNPackagesFactory.ets、Index.ets 等 ArkTS 文件，已完成 Debug 包的集成）。

0.72 版本说明：如果您使用的是 RNOH 0.72.x 版本，请参考 0.72 版本的 RNOH 包使用指南。

1. 构建方式概述

RNOH 提供两种构建方式，适用于不同的开发阶段和场景：

对比项	Debug 包	Release 包
C++ 代码	源码形式（`src/main/cpp`），随工程一起编译	预编译 `.so`（`libs/arm64-v8a`），直接链接
C++ 头文件	全量源码头文件	精简公共头文件（`include`）
ArkTS 代码	源码形式，可调试	源码形式
编译速度	慢（需全量编译 C++）	快（仅编译应用层少量代码）
包体积	较大	较小
适用场景	开发调试、需要修改或调试 C++ 层代码	生产发布、日常开发编译加速
获取方式	从 `react-native-harmony` npm 包中提取 debug `.har`	从 `react-native-harmony` npm 包中提取 release `.har`

推荐选择：日常开发使用 Debug 包快速验证，正式发布使用 Release 包提升性能和编译速度。

2. Debug 包使用

完成环境搭建后，Debug 包已集成完毕。以下仅说明日常使用流程。如需了解完整配置步骤（CPP 侧、ArkTS 侧），请参考环境搭建。

2.1 获取 Debug 包

在 RN 工程根目录下安装鸿蒙化依赖包（x.x.x 替换为实际版本号）：

npm i @react-native-oh/react-native-harmony@x.x.x

安装完成后，debug 包位于：

node_modules/@react-native-oh/react-native-harmony/react_native_openharmony.har

2.2 Debug 包概述

Debug 包以源码形式发布，包含完整的 C++ 源码和 ArkTS 源码。C++ 代码随工程一起全量编译，支持源码级断点调试。

2.3 日常使用

日常开发流程：

修改 RN 代码 → 在 RN 工程中执行 npm run dev 重新生成 bundle
替换 bundle → 将生成的 bundle.harmony.js 复制到 entry/src/main/resources/rawfile/
运行应用 → 点击 Run > Run 'entry'

首次编译较慢：由于需要全量编译 C++ 代码，请耐心等待。后续增量编译速度会明显加快。

2.4 版本升级

当需要升级 Debug 包版本时：

npm i @react-native-oh/react-native-harmony@新版本号

从下载的 react-native-harmony/ 目录中获取新的 debug 包，替换项目中使用的 har 包，然后重新编译。

2.5 与 Release 包的切换

如需切换到 Release 包以提升编译速度，请参考第3章 Release 包使用。

3. Release 包使用

3.1 什么是 Release 包

Release 包是 RNOH 预编译的鸿蒙原生模块，将 C++ 核心代码编译为 .so 动态库。与 Debug 包相比，Release 包编译速度更快、包体积更小，适合生产发布和日常开发编译加速。

3.2 Release 包内部结构

解压 release .har 包后，关键目录结构如下：

@rnoh/react-native-openharmony/
├── include/                              # C++ 公共头文件（精简版）
│   ├── RNOH/                             # RNOH 核心头文件
│   ├── react-native-harmony.cmake        # 统一构建配置文件
│   └── third-party/                      # folly、glog、boost 等第三方头文件
└── libs/
    └── arm64-v8a/                        # 预编译 .so 动态库
        ├── librnoh_semi.so               # RNOH 核心 C++ 库
        ├── libhermes.so                  # Hermes JS 引擎
        ├── libjsi.so                     # JSI 接口
        └── ...                           # 其他依赖库

3.3 获取 Release 包

通过 npm 安装后提取

在 RN 工程根目录下安装鸿蒙化依赖包（x.x.x 替换为实际版本号）：

npm i @react-native-oh/react-native-harmony@x.x.x

安装完成后，release 包位于：

node_modules/@react-native-oh/react-native-harmony/react_native_openharmony_release.har

版本确认

确认获取的 release 包版本与项目要求的版本一致。

3.4 从 Debug 切换到 Release

假设已有一个可正常运行的 Debug 版本鸿蒙工程 MyApplication，以下是从 Debug 切换到 Release 的操作步骤。

放置 Release 包

将 react_native_openharmony_release.har 复制到项目中的某个目录下（以下示例使用 libs 目录，可根据实际项目结构自行调整路径）：

MyApplication/
├── libs/
│   └── react_native_openharmony_release.har
└── entry/
    └── ...

修改 oh-package.json5

打开 MyApplication/entry/oh-package.json5，将依赖替换为 release 包的实际路径：

修改前（Debug 版本）：

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "x.x.x"
  }
}

修改后（Release 版本）：

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "file:../libs/react_native_openharmony_release.har"
  }
}

file:../libs/ 表示相对于 entry/oh-package.json5 的路径，此处指向项目根目录的 libs/ 文件夹。

如果在工程根目录的 oh-package.json5 添加了 overrides 字段的"@rnoh/react-native-openharmony"，需要同步修改。

3.5 替换 CMakeLists.txt

Release 包的 C++ 构建方式与 Debug 包不同，必须修改 CMakeLists.txt。

根据下面的改动调整 MyApplication/entry/src/main/cpp/CMakeLists.txt 文件：

set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")

- set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp")
+ set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/include")
set(RNOH_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/generated")
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
add_compile_definitions(WITH_HITRACE_SYSTRACE)
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use

- add_subdirectory("${RNOH_CPP_DIR}" ./rn)
+ include("${RNOH_CPP_DIR}/react-native-harmony.cmake")

ArkTS 侧代码（EntryAbility.ets、RNPackagesFactory.ets、Index.ets）无需修改，与 Debug 版本完全一致。

3.6 同步依赖并编译运行

注意：Release 模式暂不支持开启混淆

在 Release 模式下，请勿在模块的 build-profile.json5 中开启混淆配置，否则可能导致运行时异常。确保 arkOptions.obfuscation.ruleOptions.enable 保持为 false 或不配置该选项。

错误配置示例（请勿使用）：
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,  // ❌ Release 模式下不支持
      // ...
    }
  }
}

按以下顺序执行：

删除旧依赖：删除 MyApplication/entry/oh_modules 文件夹。
清理缓存：在 DevEco Studio 中点击 Build > Clean Project。
同步依赖：点击 File > Sync and Refresh Project，等待 ohpm install 完成。

har 包体积较大（通常 50MB+），此步耗时较长。务必等待 IDE 右下角的 SyncData 进度条消失。
切换构建模式：在 DevEco Studio 工具栏中将 Build Mode 从 debug 切换为 Release。

配置签名：Release 包需要签名才能安装到真机。在 DevEco Studio 中点击 File > Project Structure > Signing Configs，添加签名证书和配置。也可以手动在项目级 build-profile.json5 中配置：

{
  "signingConfigs": [
    {
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "certpath": "path/to/cert.cer",
        "storePassword": "your_password",
        "keyAlias": "your_alias",
        "keyPassword": "your_key_password",
        "profile": "path/to/profile.p7b",
        "signAlg": "SHA256withECDSA",
        "storeFile": "path/to/store.p12"
      }
    }
  ]
}

运行：连接真机或启动模拟器，点击 **Run > Run 'entry'`。

Sync and Refresh Project 步骤中会同步执行编译，无需手动触发 Build。

4. CMake 配置详解（Release vs Debug）

Release 包和 Debug 包的 CMakeLists.txt 有本质区别，理解这些差异有助于排查问题和进行定制。

4.1 核心差异对照

配置项	Debug 包	Release 包	说明
`RNOH_CPP_DIR` 路径	`src/main/cpp`	`include`	Debug 包包含完整 C++ 源码，Release 包仅包含精简头文件
构建配置引入	`add_subdirectory` 递归编译	`include(...cmake)` 统一配置	Release 使用 `react-native-harmony.cmake` 简化配置
预编译库链接	无需手动配置	自动链接	`react-native-harmony.cmake` 自动处理所有预编译库链接

4.2 关键配置解析

路径变量

set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

指向 entry/oh_modules 目录，ohpm 安装 release har 包后，所有文件解压至此。

set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/include")

指向 Release 包中的 C++ 公共头文件目录。注意：Debug 包使用 src/main/cpp，Release 包使用 include。

react-native-harmony.cmake

这是统一构建配置文件，自动处理：

预编译 .so 库的链接目录配置
所有必需库的 target_link_libraries 配置
头文件搜索路径配置
编译选项和宏定义

开发者只需一行 include("${RNOH_CPP_DIR}/react-native-harmony.cmake") 即可完成所有配置。

5. 版本升级

5.1 Release 包升级

升级 Release 包版本时：

npm i @react-native-oh/react-native-harmony@新版本号

从下载的 react-native-harmony/ 目录中获取新的 release 包，替换 libs/ 目录中的 .har 文件，更新 entry/oh-package.json5 中的文件名，删除 entry/oh_modules，执行 File > Sync and Refresh Project，然后重新编译。

本版本使用 react-native-harmony.cmake 统一管理配置，通常无需同步更新 CMakeLists.txt。除非新版本有特殊的配置要求，请参考对应版本的 release notes。

5.2 Debug 包升级

升级 Debug 包版本时：

npm i @react-native-oh/react-native-harmony@新版本号

从下载的 react-native-harmony/ 目录中获取新的 debug 包，替换项目中使用的 har 包，删除 entry/oh_modules，执行 File > Sync and Refresh Project，然后重新编译。

6. 常见问题排查

Q1：编译报错找不到头文件

现象：fatal error: 'RNOH/xxx.h' file not found

排查：

确认 CMakeLists.txt 中 RNOH_CPP_DIR 指向是否正确：
- Debug 包应指向 src/main/cpp
- Release 包应指向 include
检查 entry/oh_modules/@rnoh/react-native-openharmony/ 目录是否存在且完整。
执行 File > Sync and Refresh Project 重新同步。