开源鸿蒙终端工具Termony构建HAP包指导手册Mac版

🔐 应用签名配置实战

❓ 为什么需要签名？

OpenHarmony 应用必须签名后才能安装到设备上。签名用于：

应用身份验证：确保应用来源可信
数据完整性：防止应用被篡改
设备兼容性：真实设备要求应用必须签名
应用商店发布：发布到应用市场必须签名

🧩 签名配置方法

Termony 支持两种签名配置方式：

自动签名（推荐）：使用 DevEco Studio 自动生成签名配置
手动签名 ：手动编辑 build-profile.json5 配置文件

✅ 方法一：使用 DevEco Studio 自动签名（推荐）

这是最简单的方式，DevEco Studio 会自动生成签名密钥和配置。

📁 步骤 1：打开项目

启动 DevEco Studio
打开项目 ：
- 选择 File → Open
- 选择 Termony 项目根目录
- 点击 OK

⚙️ 步骤 2：配置签名

打开签名配置界面：
- 选择 File → Project Structure...
- 或者使用快捷键：⌘ + ;（Mac）或 Ctrl + Alt + Shift + S（Windows/Linux）
进入签名配置：
- 在左侧选择 Signing Configs
- 点击 + 按钮添加新的签名配置
选择签名类型：
- Debug 签名：用于开发和测试（推荐首次使用）
- Release 签名：用于正式发布
自动签名配置：
- 选择 Automatically generate signing（自动生成签名）
- DevEco Studio 会自动：
  - 生成密钥库文件（.p12）
  - 生成证书文件（.cer）
  - 生成签名配置文件（.p7b）
  - 配置 build-profile.json5
保存配置：
- 点击 Apply 应用配置
- 点击 OK 保存并关闭

🧪 步骤 3：验证签名配置

签名配置完成后，检查 build-profile.json5 文件：

bash 复制代码

# 查看签名配置
cat build-profile.json5 | grep -A 10 "signingConfigs"

# 应该看到类似以下内容：
# "signingConfigs": [
#   {
#     "name": "default",
#     "type": "HarmonyOS",
#     "material": {
#       "certpath": "/Users/.../.cer",
#       "keyAlias": "debugKey",
#       ...
#     }
#   }
# ]

验证要点：

✅ signingConfigs 数组不为空
✅ material 对象包含所有必需字段：
- certpath：证书文件路径
- storeFile：密钥库文件路径
- profile：签名配置文件路径
- keyAlias：密钥别名
- keyPassword：密钥密码（加密）
- storePassword：密钥库密码（加密）
- signAlg：签名算法

✍️ 方法二：手动配置签名

如果已有签名密钥，可以手动编辑 build-profile.json5。

📦 步骤 1：准备签名材料

确保你有以下文件：

密钥库文件 （.p12）：包含私钥和证书
证书文件 （.cer）：应用证书
签名配置文件 （.p7b）：OpenHarmony 签名配置

📝 步骤 2：编辑 build-profile.json5

打开 build-profile.json5，添加签名配置：

json5 复制代码

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "certpath": "/path/to/your/certificate.cer",
          "keyAlias": "yourKeyAlias",
          "keyPassword": "encrypted_password_hex",
          "profile": "/path/to/your/profile.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "/path/to/your/keystore.p12",
          "storePassword": "encrypted_password_hex"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",  // 关联签名配置
        ...
      }
    ],
    ...
  }
}

重要说明：

keyPassword 和 storePassword 需要使用 sign.js 加密后的十六进制字符串
密码加密方法：node sign.js <密钥目录> <原始密码>

🧪 步骤 3：验证配置

bash 复制代码

# 检查配置文件格式
python3 -m json.tool build-profile.json5 > /dev/null && echo "配置格式正确" || echo "配置格式错误"

# 检查签名文件是否存在
python3 -c "import json; c=json.load(open('build-profile.json5')); m=c['app']['signingConfigs'][0]['material']; import os; print('证书文件:', os.path.exists(m['certpath'])); print('密钥库文件:', os.path.exists(m['storeFile'])); print('配置文件:', os.path.exists(m['profile']))"

🧯 签名配置常见问题

问题 1：签名配置为空

错误信息：

复制代码

IndexError: list index out of range

原因：build-profile.json5 中的 signingConfigs 为空数组。

解决方案：

使用 DevEco Studio 自动配置签名（推荐）
或手动编辑 build-profile.json5 添加签名配置

问题 2：签名文件路径错误

错误信息：

复制代码

FileNotFoundError: [Errno 2] No such file or directory: '/path/to/cert.cer'

解决方案：

检查签名文件路径是否正确
确保文件存在且可读
使用绝对路径而不是相对路径

问题 3：密码解密失败

错误信息：

复制代码

Error: Failed to decrypt password

解决方案：

确保 sign.js 脚本可用
检查密码加密格式是否正确
重新使用 DevEco Studio 生成签名配置

问题 4：签名算法不匹配

错误信息：

复制代码

Unsupported signature algorithm

解决方案：

确保 signAlg 为 SHA256withECDSA
检查密钥库是否支持该算法

✅ 签名配置验证清单

在构建 HAP 包之前，请确认：

DevEco Studio 已安装并打开项目
签名配置已添加（signingConfigs 不为空）
签名文件路径正确且文件存在
products 中的 signingConfig 指向正确的签名配置名称
build-profile.json5 格式正确（可通过 JSON 验证）

🏗️ HAP 包构建实战

❓ 什么是 HAP？

HAP（OpenHarmony Application Package）是 OpenHarmony 应用的安装包格式，类似于 Android 的 APK。HAP 包包含应用的所有代码、资源、配置文件和原生库。

🛠️ 构建 HAP 包

✅ 前置条件

在构建 HAP 包之前，请确保：

✅ 已完成环境配置（Homebrew、开发工具等）
✅ DevEco Studio 已安装（用于提供 OpenHarmony SDK 和构建工具）
✅ 应用签名已配置（**重要！**必须先在 DevEco Studio 中配置签名）
✅ HNP 包已构建（./create-hnp.sh 已执行）
✅ 环境变量已正确设置

⚠️ 重要提示

构建HAP包之前需要使用DevEco Studio打开为应用配置ArkUI-X路径。

如果未配置，构建过程会显示错误：

shell 复制代码

Installing dependencies...
 ERR_PNPM_FETCH_404  GET https://repo.huaweicloud.com/repository/npm/@ohos%2Fhvigor-ohos-arkui-x-plugin: Not Found - 404

This error happened while installing a direct dependency of /Users/baixm/.hvigor/project_caches/ff796b85a5dcea0ae785783bb7e61d4b/workspace

@ohos/hvigor-ohos-arkui-x-plugin is not in the npm registry, or you have no permission to fetch it.

No authorization header was set for the request.
> hvigor ERROR: 00308002 Operation Error
Error Message: /Users/baixm/.hvigor/wrapper/tools/node_modules/.bin/pnpm install execute failed.

* Try the following: 
  > See above for details.

签名配置必须在构建HAP包之前完成！

如果未配置签名，构建过程会显示错误：

shell 复制代码

> hvigor ERROR: Failed :entry:default@SignHap... 
> hvigor ERROR: 00303107 Configuration Error
Error Message: Invalid storeFile value. Make sure it is not null or empty. The file must be included in '/Users/tetcl/.ohos/config/default_Termony_moe-OdT8YFdEgcGrfK_31DBCd0zmKNQIKzz8AgaZFvE=.p12'. At file: /Users/baixm/HarmonyOSPC/szkygc/Termony/build-profile.json5

* Try the following:
  > Please check signingConfigs in root project file


* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --debug option to get more log output.

> hvigor ERROR: BUILD FAILED in 3 s 884 ms

推荐流程：

先在 DevEco Studio 中配置签名（见上一章节）
验证签名配置正确
再执行 ./build-macos.sh 构建 HAP 包

🧭 构建步骤

步骤 1：检查 HNP 包

确保 HNP 包已构建并复制到应用目录：

bash 复制代码

# 检查 HNP 包是否存在
ls -lh entry/hnp/arm64-v8a/*.hnp

# 应该看到：
# -rw-r--r--  ... entry/hnp/arm64-v8a/base.hnp
# -rw-r--r--  ... entry/hnp/arm64-v8a/base-public.hnp

步骤 2：验证签名配置

在执行构建之前，先验证签名配置：

bash 复制代码

# 检查签名配置是否存在
python3 -c "import json; c=json.load(open('build-profile.json5')); print('签名配置数量:', len(c['app']['signingConfigs'])); print('签名配置名称:', c['app']['signingConfigs'][0]['name'] if c['app']['signingConfigs'] else '无')"

# 应该输出：
# 签名配置数量: 1
# 签名配置名称: default

如果签名配置为空，请先参考上一章节配置签名。

步骤 3：执行构建脚本

bash 复制代码

# 进入项目根目录
cd /path/to/Termony

# 执行构建脚本
./build-macos.sh

🔍 构建过程详解

执行 ./build-macos.sh 后，脚本会执行以下步骤：

1. 环境准备

bash 复制代码

# 设置工具目录路径
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents

# 设置 SDK 路径
export DEVECO_SDK_HOME=$TOOL_HOME/sdk
export OHOS_SDK_HOME=$TOOL_HOME/sdk/default/openharmony

# 添加工具到 PATH
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH      # OpenHarmony 包管理器
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH    # OpenHarmony 构建工具
export PATH=$TOOL_HOME/tools/node/bin:$PATH      # Node.js

2. 使用 Hvigor 构建 HAP

bash 复制代码

hvigorw assembleHap

Hvigor 是 OpenHarmony 的构建工具（类似 Gradle），会执行以下任务：

PreBuild：构建前准备
CreateModuleInfo：创建模块信息
GenerateMetadata：生成元数据
ConfigureCmake：配置 CMake（原生代码构建）
ProcessProfile：处理配置文件
CompileResource：编译资源文件
BuildJS：构建 JavaScript/ArkTS 代码
BuildNativeWithNinja：使用 Ninja 构建原生代码
CompileArkTS：编译 ArkTS 代码
PackageHap：打包成 HAP 格式
SignHap：签名 HAP 包（如果配置了签名）

3. 添加 HNP 包到 HAP

bash 复制代码

# 进入 entry 目录
pushd entry

# 将 hnp 目录添加到 HAP 包中
# -1：最快的压缩级别（不压缩，仅存储）
# -r：递归压缩目录
zip -1 -r ../entry/build/default/outputs/default/entry-default-unsigned.hap hnp

# 返回之前的目录
popd

4. 签名 HAP 包

bash 复制代码

# 调用 Python 签名脚本
python3 sign.py \
  ./entry/build/default/outputs/default/entry-default-unsigned.hap \
  ./entry/build/default/outputs/default/entry-default-signed.hap

注意：

如果 build-profile.json5 中已配置签名，构建脚本会自动签名 HAP 包
如果未配置签名，构建会显示警告，但未签名的 HAP 包仍然可以用于模拟器测试
强烈建议在构建前配置签名，以便安装到真实设备

📦 构建输出

成功标志：

构建成功后，你会看到：

未签名 HAP 包：

bash 复制代码

ls -lh entry/build/default/outputs/default/entry-default-unsigned.hap
# 输出：-rw-r--r--  1 user  staff   4.6M Nov 15 12:33 entry-default-unsigned.hap

HAP 包内容：

bash 复制代码

unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap
# 输出：
# Archive:  entry-default-unsigned.hap
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#      2196  11-15-2025 12:33   module.json
#      1031  11-15-2025 12:33   resources.index
#   1473040  11-15-2025 12:33   libs/arm64-v8a/libentry.so
#   1262248  11-15-2025 12:33   libs/arm64-v8a/libc++_shared.so
#   109728  11-15-2025 12:33   resources/rawfile/Inconsolata-Bold.ttf
#   108684  11-15-2025 12:33   resources/rawfile/Inconsolata-Regular.ttf
#    27648  11-15-2025 12:33   ets/modules.abc
#   826378  11-15-2025 12:30   hnp/arm64-v8a/base.hnp
#   826378  11-15-2025 12:30   hnp/arm64-v8a/base-public.hnp
#       ... (其他文件)

HAP 包结构：

复制代码

entry-default-unsigned.hap
├── module.json              # 模块配置文件
├── resources.index          # 资源索引文件
├── libs/                    # 原生库文件
│   └── arm64-v8a/
│       ├── libentry.so      # 终端引擎库
│       └── libc++_shared.so # C++ 标准库
├── resources/               # 资源文件
│   ├── rawfile/             # 原始资源文件
│   │   ├── Inconsolata-Bold.ttf
│   │   └── Inconsolata-Regular.ttf
│   ├── base/                # 基础资源
│   │   ├── media/           # 媒体资源
│   │   └── profile/         # 配置文件
├── ets/                     # ArkTS 编译产物
│   ├── modules.abc          # 字节码文件
│   └── sourceMaps.map       # 源码映射
├── hnp/                     # HNP 包目录
│   └── arm64-v8a/
│       ├── base.hnp         # HNP 包
│       └── base-public.hnp  # 公开 HNP 包
└── pack.info                # 打包信息

⏱️ 构建时间

首次构建：10-30 秒（取决于硬件）
增量构建：几秒（只编译修改的文件）
原生代码构建：1-2 秒（使用 Ninja）
ArkTS 编译：2-3 秒

🧯 常见问题

问题 1：找不到 hvigorw

错误信息：

复制代码

command not found: hvigorw

解决方案：

确保 DevEco Studio 已安装
检查 $TOOL_HOME/tools/hvigor/bin 是否在 PATH 中

或者手动设置 PATH：

bash 复制代码

export PATH=/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH

问题 2：签名配置缺失

错误信息：

复制代码

IndexError: list index out of range

原因：build-profile.json5 中的 signingConfigs 为空数组。

解决方案：

重要：必须在构建之前配置签名！

使用 DevEco Studio 自动配置签名（推荐）：
- 打开 DevEco Studio
- 打开 Termony 项目
- 选择 File → Project Structure → Signing Configs
- 点击 + 添加签名配置
- 选择 Automatically generate signing（自动生成签名）
- 点击 Apply 和 OK 保存
- 验证 build-profile.json5 中已添加签名配置
手动编辑 build-profile.json5（高级用户）：
- 参考"应用签名配置实战"章节
- 确保所有签名文件路径正确
- 密码需要使用 sign.js 加密

验证签名配置：

bash 复制代码

# 检查签名配置
python3 -c "import json; c=json.load(open('build-profile.json5')); print('签名配置数量:', len(c['app']['signingConfigs']))"

注意：

未签名的 HAP 包可以用于模拟器测试，但无法安装到真实设备
签名配置后，构建脚本会自动签名 HAP 包
签名后的 HAP 包可以安装到真实设备

问题 3：HNP 包未找到

错误信息：

复制代码

zip: hnp: No such file or directory

解决方案：

确保已执行 ./create-hnp.sh 构建 HNP 包
检查 entry/hnp/arm64-v8a/ 目录是否存在
确保 HNP 包已复制到应用目录

问题 4：构建警告

警告信息：

复制代码

WARN: Function may throw exceptions. Special handling is required.
WARN: 'showToast' has been deprecated.

说明：这些是代码警告，不影响构建，但建议修复：

添加异常处理
使用新的 API 替代已废弃的 API

问题 5：原生代码构建失败

解决方案：

bash 复制代码

# 清理构建产物
cd entry
rm -rf build

# 重新构建
cd ..
./build-macos.sh

🚀 构建优化建议

使用增量构建：
- Hvigor 会自动检测修改的文件
- 只重新编译修改的部分
并行构建：
- Hvigor 默认使用多线程构建
- 可以通过 hvigor.properties 配置线程数
缓存构建产物：
- 保留 entry/build 目录
- 避免不必要的清理

🧪 验证构建结果

方法 1：检查文件

bash 复制代码

# 检查 HAP 包是否存在
ls -lh entry/build/default/outputs/default/entry-default-unsigned.hap

# 检查包大小（应该约 4-5MB）
du -h entry/build/default/outputs/default/entry-default-unsigned.hap

# 检查包内容
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap

方法 2：检查包结构

bash 复制代码

# 解压并查看包结构
cd /tmp
unzip -q /path/to/Termony/entry/build/default/outputs/default/entry-default-unsigned.hap
tree -L 3

方法 3：验证关键文件

bash 复制代码

# 检查原生库是否存在
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap | grep libentry.so

# 检查 HNP 包是否存在
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap | grep base.hnp

# 检查字体文件是否存在
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap | grep Inconsolata

🔏 签名 HAP 包（可选）

如果需要在真实设备上安装，需要签名 HAP 包：

步骤 1：配置签名信息

在 DevEco Studio 中配置签名，或手动编辑 build-profile.json5。

步骤 2：执行签名

bash 复制代码

python3 sign.py \
  ./entry/build/default/outputs/default/entry-default-unsigned.hap \
  ./entry/build/default/outputs/default/entry-default-signed.hap

步骤 3：验证签名

bash 复制代码

# 检查签名后的 HAP 包
ls -lh entry/build/default/outputs/default/entry-default-signed.hap