OpenHarmony HAP 构建工具

功能描述

这个 skill 提供了 OpenHarmony HAP 应用的构建和签名功能，包括：

1. 环境检查：自动检查编译所需的环境配置
2. 版本验证：验证 SDK 版本与项目配置的一致性
3. HAP 构建：执行 HAP 应用的编译
4. HAP 签名：对编译生成的 HAP 文件进行签名
5. 清除签名：清除签名相关的临时文件

应用示例与提示词

需 HOS_CLT_PATH、OHOS_SDK_PATH；在 napi_generator 仓库根 执行时脚本路径如下，<项目目录> 多为 src/skills/ohhap/NativeProj46R 或你自建的 HAP 工程绝对路径。

场景	命令示例	提示词示例
编译 HAP	python3 src/skills/ohhap/hapbuild.py build src/skills/ohhap/NativeProj46R	「用 ohhap 编译 NativeProj46R 模板工程」
指定 product/mode	python3 src/skills/ohhap/hapbuild.py build <项目> default release	「打成 release 主包」
签主包	python3 src/skills/ohhap/hapbuild.py sign <项目> release	「对未签名 HAP 做 release 签名」
编测试包	python3 src/skills/ohhap/hapbuild.py build-test <项目>	「只构建 ohosTest HAP」
清签名	python3 src/skills/ohhap/hapbuild.py clean-sign <项目>	「清除 autosign 临时文件」
查看用法	python3 src/skills/ohhap/hapbuild.py（无参打印命令列表）	「hapbuild 支持哪些子命令」

环境要求

必需的环境变量

• HOS_CLT_PATH: HarmonyOS Command Line Tools 路径

  • 例如: <本机 Command Line Tools 根目录>
  • 需要包含 version.txt 文件

• OHOS_SDK_PATH: OpenHarmony SDK 路径

  • 例如: <本机 ohos-sdk 根目录>
  • 需要包含 daily_build.log 文件

自动命令行签名（与 build / build-test 串联）

在 OHOS_HAPSIGNER_RESULT 指向 hapsigner 证书目录（含 OpenHarmony.p12、rootCA.cer、subCA.cer 及对应 profile 的 pem）时，build / build-test 成功后会自动执行与 sign 子命令相同的命令行签名，无需再单独跑 sign。

• OHOS_HAPSIGNER_AUTO_SIGN: 默认开启；设为 0 / false / no / off 则只构建、不自动签名。
• OHOS_HAPSIGNER_PROFILE: 可选，显式指定 debug 或 release；未设时按构建模式选择（release 构建对应 release 签名，否则为 debug）。若推断为 debug 但证书目录没有 OpenHarmonyProfileDebug.pem（仅自备 release 材料时常见），自动改用 release 签名。
• 若未设置 OHOS_HAPSIGNER_RESULT 且本机不存在默认的 ~/ohos/.../hapsigner/autosign/result，则跳过自动签名（构建仍计为成功）。

说明：hvigor 内置 SignHap 依赖 DevEco 加密密码与 material/ 密钥材料；自动签名走 hap-sign-tool 命令行，与 build-profile.json5 中明文密码是否通过校验无关。静态 XTS 工程宜保持 signingConfigs 为空，由本流程出 unsigned 后再自动签出 signed HAP。

工具版本要求

• Node.js: v18.20.1
• Hvigor: 6.21.2
• 项目目录: 需要包含 build-profile.json5 配置文件

使用方法

命令行方式

构建 HAP

# 基本用法（使用默认 product 和 debug 模式）
python3 src/skills/ohhap/hapbuild.py build <project_dir>

# 向后兼容：直接使用项目目录（自动识别为 build 命令）
python3 src/skills/ohhap/hapbuild.py <project_dir>

# 指定 product 和 build_mode
python3 src/skills/ohhap/hapbuild.py build <project_dir> <product> <build_mode>

# 示例
python3 src/skills/ohhap/hapbuild.py build /path/to/project
python3 src/skills/ohhap/hapbuild.py build /path/to/project default debug
python3 src/skills/ohhap/hapbuild.py build /path/to/project default release

一次跑通「构建 + 自动签名」（静态 XTS 等，工程内需有 signing-materials 或等价目录并设 OHOS_HAPSIGNER_RESULT）：

export HOS_CLT_PATH=<Command-Line-Tools 根目录>
export OHOS_SDK_PATH=<openharmony/static 等 SDK 根，需能解析到 hap-sign-tool.jar>
export OHOS_HAPSIGNER_RESULT=<含 p12/CA/pem 的目录>
export OHOS_USE_HVIGOR_STATIC=1   # 使用 hvigor-static 时
python3 src/skills/ohhap/hapbuild.py build <project_dir> default debug
# 成功则 exit 0，且生成 entry-default-unsigned.hap 与 entry-default-signed.hap（路径以模块为准）

签名 HAP

# 使用 release profile 签名（默认）
python3 src/skills/ohhap/hapbuild.py sign <project_dir>

# 使用 debug profile 签名
python3 src/skills/ohhap/hapbuild.py sign <project_dir> debug

# 使用 release profile 签名
python3 src/skills/ohhap/hapbuild.py sign <project_dir> release

# 示例
python3 src/skills/ohhap/hapbuild.py sign /path/to/project
python3 src/skills/ohhap/hapbuild.py sign /path/to/project release

清除签名

# 清除签名（删除 autosign 目录）
python3 src/skills/ohhap/hapbuild.py clean-sign <project_dir>

# 示例
python3 src/skills/ohhap/hapbuild.py clean-sign /path/to/project

对话方式

• "编译 OpenHarmony 项目 /path/to/project"
• "构建 HAP 应用 /path/to/project"
• "使用 release 模式编译项目 /path/to/project"
• "对项目 /path/to/project 的 HAP 进行签名"
• "清除项目 /path/to/project 的签名"

工作流程

1. 环境检查

   • 检查 HOS_CLT_PATH 和 OHOS_SDK_PATH 环境变量
   • 检查 Node.js 版本
   • 检查 Hvigor 版本
   • 读取 Command Line Tools 版本信息（从 version.txt）
   • 读取 SDK 版本信息（从 daily_build.log）

2. 版本验证

   • 解析项目的 build-profile.json5 配置文件
   • 提取 targetSdkVersion 和 compatibleSdkVersion
   • 验证 SDK 版本与项目配置的一致性
   • 检查 SDK 中是否存在项目所需的 API 级别

3. 执行构建

   • 使用 node $HOS_CLT_PATH/hvigor/bin/hvigorw.js 替代项目内的 hvigorw
   • 执行 node hvigorw.js clean --no-daemon 清理项目
   • 执行 node hvigorw.js --mode module -p product=default assembleHap --analyze=normal --parallel --incremental --daemon 构建主 HAP
   • 单元测试 HAP：node hvigorw.js --mode module -p module=entry@ohosTest -p isOhosTest=true -p product=default -p buildMode=test assembleHap --analyze=normal --parallel --incremental --daemon
   • 自动检查生成的 HAP 文件

4. 构建后自动签名（默认开启，条件见上文「自动命令行签名」）

   • 若证书目录可用，在构建成功后继续执行 sign 同逻辑的 hap-sign-tool 流程，生成 signed HAP。

5. HAP 签名流程（sign 子命令或上述自动签名，8 步）

   • 步骤 1: 在工程根目录创建 autosign 目录
   • 步骤 2: 拷贝证书文件和相关工具文件到 autosign 目录
   • 步骤 3: 修改模板 JSON 文件中的 bundle-name（从 app.json5 读取）
   • 步骤 4: 生成应用签名证书密钥对
   • 步骤 5: 生成应用签名证书
   • 步骤 6: 对 profile 文件进行签名
   • 步骤 7: 对应用包进行签名
   • 步骤 8: 验证应用包签名

版本信息解析

Command Line Tools 版本文件格式

$HOS_CLT_PATH/version.txt 文件格式：

# ======================
# Command Line Tools(linux-x64)
# Version: 6.0.1.260
# ======================
...
hvigor 6.21.2
ohpm 6.0.1

SDK 版本文件格式

$OHOS_SDK_PATH/daily_build.log 文件包含：

'versionName': 'OpenHarmony_6.0.0.47'

项目配置文件格式

build-profile.json5 文件包含：

{
  "app": {
    "products": [
      {
        "targetSdkVersion": "6.0.0(20)",
        "compatibleSdkVersion": "6.0.0(20)"
      }
    ]
  }
}

其中 (20) 表示 API 级别，对应 SDK 中的 sdk/openharmony/20/ 目录。

示例输出

================================================================================
检查编译环境...
================================================================================
✓ HarmonyOS Command Line Tools 路径: <你的 Command Line Tools 目录>
  SDK名称: Command Line Tools
  运行系统: linux-x64
  版本: 6.0.1.260
  Hvigor版本: 6.21.2
  OHPM版本: 6.0.1
✓ OpenHarmony SDK 路径: <你的 ohos-sdk 目录>
  SDK版本: OpenHarmony_6.0.0.47
✓ Node.js 版本: v18.20.1 (符合要求)
✓ Hvigor 版本: 6.21.2 (符合要求)

================================================================================
验证版本一致性...
================================================================================
项目配置:
  targetSdkVersion: 6.0.0(20)
  compatibleSdkVersion: 6.0.0(20)
  API级别: 20
✓ SDK 主版本一致: 6.0
✓ SDK 中存在 API 20

================================================================================
开始构建 HAP...
================================================================================
工作目录: /path/to/project

执行清理...
命令: hvigorw clean --no-daemon

执行构建...
命令: hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

✓ HAP 构建成功！

HAP 签名功能说明

签名流程

签名功能会自动执行以下步骤：

1. 创建 autosign 目录：在项目根目录创建 autosign 目录用于存放签名相关文件
2. 拷贝证书文件：从 ~/ohos/60release/src/developtools/hapsigner/autosign/result/ 拷贝证书文件
3. 拷贝工具文件：从 $OHOS_SDK_PATH/linux/toolchains/lib/ 拷贝签名工具
4. 修改模板文件：自动从 AppScope/app.json5 读取 bundleName 并更新到模板文件
5. 生成密钥对：使用 hap-sign-tool.jar 生成应用签名证书密钥对
6. 生成证书：生成应用签名证书链
7. 签名 profile：对 profile 文件进行签名
8. 签名 HAP：对未签名的 HAP 文件进行签名
9. 验证签名：验证签名后的 HAP 文件

签名文件位置

• 签名的 HAP 文件: <project_dir>/autosign/app1-signed.hap
• 证书文件: <project_dir>/autosign/app1.cer
• Profile 文件: <project_dir>/autosign/app1-profile.p7b

签名要求

• 需要先编译项目生成未签名的 HAP 文件
• 需要 OHOS_SDK_PATH 环境变量指向正确的 SDK 路径
• 需要证书文件位于 ~/ohos/60release/src/developtools/hapsigner/autosign/result/
• 项目需要包含 AppScope/app.json5 文件，且包含有效的 bundleName

清除签名

使用 clean-sign 命令可以删除 autosign 目录，清除所有签名相关的临时文件。

脚本文件

• hapbuild.py: HAP 构建和签名主脚本
• crosscompile.py: 交叉编译脚本（待实现）

注意事项

1. 确保在项目根目录中运行脚本，或者确保项目目录包含 hvigorw 脚本
2. 环境变量必须在运行前正确设置
3. 版本不一致时会显示警告，但构建仍会继续
4. 构建过程可能需要较长时间，请耐心等待
5. 签名功能需要 Java 环境，确保 java 命令可用
6. 签名过程中会使用默认密码 123456，生产环境请使用自己的证书和密码