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