rnoh-build-har

跨平台 CLI 工具 — 为 React Native 三方库构建 HarmonyOS HAR 模块（macOS / Windows / Linux）

为什么需要这个工具

React Native 鸿蒙三方库的 harmony/ 目录通常只包含模块源码，不包含完整的 HarmonyOS 工程级配置（build-profile.json5、oh-package.json5、hvigorfile.ts 等）。手动用 DevEco Studio 构建需要：

1. 创建完整的壳工程
2. 配置工程级文件
3. 执行构建
4. 拷贝产物
5. 清理临时文件

本工具自动完成以上全部步骤，且跨平台运行，无需 bash / find / rsync / file 等系统命令。

安装

全局安装

npm install -g rnoh-build-har

npx 直接运行（无需安装）

npx rnoh-build-har rntpc_react-native-netinfo

项目内安装

npm install --save-dev rnoh-build-har

然后在 package.json 中添加 script：

{
  "scripts": {
    "build:har": "rnoh-build-har"
  }
}

前置要求

依赖	必需	说明
Node.js ≥ 18	✅	运行时
devecocli	✅	DevEco Studio 自带，或 npm install -g @deveco/deveco-cli@latest
DevEco SDK	✅	通过 DevEco Studio 安装

不再需要 python3、rsync、bash、find、file 等系统命令 — 全部由 Node.js 内置模块替代。

用法

Usage: rnoh-build-har [api-version] [version] [path] [--module-name <name>] [--build-mode <mode>]

  api-version     HarmonyOS API version (pure integer, e.g. 12, 16)
                  Maps to compatibleSdkVersion: 12→'5.0.0(12)', 16→'5.0.4(16)'
                  See: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/overview-allversion
  version         @rnoh/react-native-openharmony ohpm version (e.g. 0.82.18)
                  Contains a dot. When specified, pulls RNOH from ohpm instead of local HAR.
  path            RN library root (harmony/ should be inside).
                  If omitted, auto-detect: check current dir, then its subdirs.
  --module-name   HAR module name; auto-detect if omitted
  --build-mode    Build mode: release (default) or debug
  --help          Show this help

Arguments are auto-detected by format:
  - Pure integer (e.g. 12, 16)        → API version
  - Dotted version (e.g. 0.82.18)     → RNOH ohpm version
  - Other non-flag argument            → library path

示例

# 自动检测当前目录或子目录中的 harmony/
rnoh-build-har

# 指定库路径
rnoh-build-har rntpc_react-native-netinfo

# 使用 ohpm 版本号替代本地 HAR（无需先 npm install）
rnoh-build-har 0.82.18 rntpc_react-native-permissions

# 指定 API 版本 + ohpm 版本 + 路径
rnoh-build-har 16 0.82.18 rntpc_react-native-permissions

# 仅指定 API 版本（使用本地 HAR）
rnoh-build-har 12 rntpc_react-native-netinfo

# 指定模块名 + debug 模式
rnoh-build-har --module-name mylib --build-mode debug

API 版本对应表

API	compatibleSdkVersion	API	compatibleSdkVersion
12	5.0.0(12)	18	5.1.0(18)
13	5.0.1(13)	19	5.1.1(19)
14	5.0.2(14)	20	6.0.0(20)
15	5.0.3(15)	21	6.0.1(21)
16	5.0.4(16)	22	6.0.2(22)
17	5.0.5(17)	23	6.1.0(23)
		24	6.1.1(24)

数据来源：HarmonyOS 版本说明

如果 harmony/build-profile.json5 已存在，将保留原有配置，不覆盖 compatibleSdkVersion。

工作流程

库根目录/
├── src/                    # RN JS/TS 源码
├── harmony/                # 鸿蒙原生模块
│   └── my_module/          # HAR 模块源码
│       └── src/main/
│           ├── module.json5
│           └── cpp/        # (可选) C++ 源码
└── package.json

脚本执行步骤：

1. 定位 harmony/ 目录和 HAR 模块
2. 检测是否依赖 @rnoh/react-native-openharmony
3. 搜索 react_native_openharmony.har（本地或 ohpm 版本）
4. 写入临时工程级配置文件（build-profile.json5 等）
5. 执行 devecocli build --modules <name> --build-mode <mode>
6. 校验产物格式（gzip tar，无 AppleDouble 文件）
7. 补全 cpp 源码（如果 devecocli 未打包 CMakeLists.txt）
8. 拷贝产物到 harmony/<module>.har
9. 清理所有临时文件和构建缓存

编程式 API

import { buildHar } from 'rnoh-build-har';

await buildHar({
  libPath: '/path/to/react-native-xxx',
  buildMode: 'release',
  // rnohVersion: '0.82.18',  // 可选：使用 ohpm 版本
  // apiVersion: 16,          // 可选：HarmonyOS API 版本（12-24）
  // moduleName: 'mylib',     // 可选：自动检测
});

API 参数

参数	类型	默认值	说明
libPath	string	自动检测	RN 三方库根目录
moduleName	string	自动检测	HAR 模块名
buildMode	'release' | 'debug'	'release'	构建模式
rnohVersion	string	-	RNOH ohpm 版本号
apiVersion	number	-	HarmonyOS API 版本号（如 12、16）

跨平台支持

平台	状态	说明
macOS	✅	完整支持
Windows	✅	完整支持（自动处理 .cmd 路径、\ 分隔符）
Linux	✅	完整支持

Windows 注意事项

• 自动检测 C:\Program Files\Huawei\DevEco Studio\tools\node\bin\devecocli.cmd
• 路径分隔符由 Node.js path 模块自动处理
• 不需要 Git Bash / WSL

产物

harmony/<module-name>.har   # gzip tar 格式，含 cpp 源码

License

Apache-2.0