OpenHarmony 应用签名配置实战指南

为何必须进行应用签名？

• 身份验证：确认应用开发者身份，防止冒名发布
• 数据完整性保护：确保应用从打包到安装过程中未被篡改
• 设备兼容性要求：真实物理设备仅允许安装已签名的应用包
• 上架前提条件：向应用市场提交应用时，签名是强制性要求

Termony 项目中的签名配置方式

• 自动签名（推荐方案）：通过 DevEco Studio 自动生成密钥与相关配置文件
• 手动签名：自行准备签名材料并编辑配置文件

build-profile.json5

推荐方式：使用 DevEco Studio 实现自动签名

第一步：打开目标项目

1. 选择项目打开入口
2. 定位至 Termony 项目的根目录并选中
3. 点击确认按钮完成加载

File → Open

OK

第二步：进入签名设置界面

• 菜单导航：依次点击对应选项
• 快捷键操作：

File → Project Structure...

? + ;

Ctrl + Alt + Shift + S

Signing Configs

+

选择签名类型

• Debug 签名：适用于开发调试阶段（首次建议选用）
• Release 签名：用于正式版本发布

启用自动签名功能

Automatically generate signing

• 创建密钥库文件（存储于指定路径）

  .p12

• 生成证书文件

  .cer

• 生成完整的签名配置文件

  .p7b

• 自动填充

  build-profile.json5

  相关字段

保存签名设置

• 点击

  Apply

  应用更改
• 随后点击

  OK

  保存并关闭窗口

第三步：验证签名配置是否生效

# 查看签名配置
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

  ：所使用的签名算法类型

备选方案：手动配置签名信息

第一步：准备必要的签名文件

• 密钥库文件（

  .p12

  ）：包含私钥及证书链
• 证书文件（

  .cer

  ）：用于身份认证的应用证书
• 签名配置文件（

  .p7b

  ）：符合 OpenHarmony 格式的配置定义

第二步：编辑 build-profile.json5 文件

build-profile.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 <密钥目录> <原始密码>

第三步：校验配置正确性

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']))"

常见签名问题及解决方案

问题一：签名配置为空

IndexError: list index out of range

build-profile.json5

signingConfigs

• 推荐使用 DevEco Studio 的自动签名功能进行配置
• 或手动编辑

  build-profile.json5

  文件，添加完整的签名配置信息

问题二：签名文件路径无效

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

• 仔细核对配置中的文件路径是否准确无误
• 确认目标文件确实存在且具备读取权限
• 建议使用绝对路径而非相对路径，避免路径解析失败

问题三：密码解密失败

Error: Failed to decrypt password

• 确保

  sign.js

  解密脚本环境正常可用
• 检查加密过程是否正确执行，输出为合法十六进制串
• 确认密码字段已按规范加密并填入配置

HAP 包构建前的签名配置检查

在开始构建 HAP 包之前，必须完成应用签名的配置。若未正确设置签名信息，构建过程将报错并中断。以下是关键检查项和常见问题的解决方案。

签名配置验证清单

• 确保 DevEco Studio 已成功安装，并已打开对应项目
• 确认签名配置已添加且内容非空（此处为图片18）
• 验证签名文件路径正确无误，且文件实际存在
• 此处为图片48 中的 此处为图片49 需指向正确的签名配置名称
• 检查配置文件格式是否符合 JSON 标准，建议使用在线工具进行语法验证

常见问题及处理方法

问题 1：密码加密格式错误

请确认输入的密钥库密码与别名密码均采用正确的加密方式，避免因格式不匹配导致解析失败。

问题 2：签名算法不兼容

错误信息：
此处为图片44

解决方案：
确保使用的算法为：
此处为图片45
支持的算法类型应为：
此处为图片46
同时检查所用密钥库是否支持该签名算法。

问题 3：未配置 ArkUI-X 路径

在构建 HAP 包前，务必通过 DevEco Studio 打开项目并配置 ArkUI-X 相关路径。否则可能出现如下错误：

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.

此问题通常由缺失 ArkUI-X 插件依赖引起，正确配置路径后可解决。

问题 4：缺少签名配置导致构建失败

若未设置签名信息，系统将提示以下错误：

> 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

这表明 storeFile 值无效或为空，请检查配置文件中的路径是否存在或拼写是否有误。

推荐操作流程

1. 在 DevEco Studio 中完成签名配置（参考前述章节）
2. 验证签名配置的完整性与准确性
3. 执行构建命令：
   此处为图片52

HAP 包构建实战指南

什么是 HAP？

HAP（OpenHarmony Application Package）是 OpenHarmony 平台上的应用程序安装包格式，功能上类似于 Android 的 APK。一个完整的 HAP 包包含应用的所有代码、资源文件、配置信息以及原生库等必要组件。

前置条件

在启动 HAP 构建流程前，请确认满足以下条件：

• 开发环境已配置完毕（包括 Homebrew 及相关工具链）
• DevEco Studio 已安装，用于提供 OpenHarmony SDK 和构建支持
• 应用签名配置已完成（至关重要！ 必须提前在 DevEco Studio 中完成）
• HNP 包已成功构建并输出（此处为图片51 已执行）
• 所有必要的环境变量均已正确设置

构建步骤

步骤 1：检查 HNP 包状态

确认 HNP 包已经生成并复制到目标应用目录中：

# 检查 HNP 包是否存在

signingConfigs

Unsupported signature algorithm

signAlg

SHA256withECDSA

products

signingConfig

./create-hnp.sh

./build-macos.sh

build-profile.json5

# 步骤 1：检查 HNP 文件是否存在
执行以下命令查看 arm64-v8a 架构下的 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：验证签名配置是否正确
在开始构建前，需确认 build-profile.json5 中已配置签名信息：

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

若输出“无”或数量为0，则表示未设置签名，请参考相关章节完成签名配置。

# 步骤 3：运行构建脚本
首先切换至项目主目录并执行构建命令：

cd /path/to/Termony
./build-macos.sh

./build-macos.sh

构建流程详细说明

当执行构建脚本后，系统将按以下顺序处理：

1. 环境变量初始化

为确保工具链可用，脚本会预先设置必要的路径：

export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
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    # Hvigor 构建引擎
export PATH=$TOOL_HOME/tools/node/bin:$PATH      # Node.js 运行时

2. 使用 Hvigor 执行 HAP 构建

Hvigor 是 OpenHarmony 的核心构建工具，功能类似于 Gradle。其主要执行任务包括：

• PreBuild：执行构建前的准备工作
• CreateModuleInfo：生成模块描述信息
• GenerateMetadata：创建应用所需的元数据文件
• ConfigureCmake：配置 CMake 以支持原生代码编译
• ProcessProfile：解析并处理 profile 配置文件
• CompileResource：编译资源如布局、字符串等
• BuildJS：转换 JavaScript 或 ArkTS 源码
• BuildNativeWithNinja：调用 Ninja 编译 C/C++ 代码
• CompileArkTS：对 ArkTS 文件进行类型检查与编译
• PackageHap：将所有组件打包成未签名的 HAP 文件
• SignHap：如有配置，自动对 HAP 进行数字签名

hvigorw assembleHap

3. 将 HNP 文件嵌入 HAP 包

构建过程中会将 hnp 目录内容添加到最终的 HAP 包中：

pushd entry
zip -1 -r ../entry/build/default/outputs/default/entry-default-unsigned.hap hnp
popd

其中参数说明：

• -1：使用最低压缩等级（仅存储，不压缩）
• -r：递归打包整个目录结构

4. 对 HAP 包进行签名

若手动控制签名过程，可运行如下命令：

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 文件位置及大小

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 内部结构

可通过 unzip 命令列出包内内容：

unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap
# 输出示例：

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 秒，具体取决于设备硬件性能。
• 增量构建：仅需几秒钟，系统只会重新编译被修改过的文件。
• 原生代码构建：使用 Ninja 构建系统，通常在 1 至 2 秒内完成。
• ArkTS 编译：平均耗时约为 2 到 3 秒。

常见问题及解决方案

问题一：hvigorw 命令无法找到

错误提示：

command not found: hvigorw

解决方法：

• 确认已正确安装 DevEco Studio。
• 检查

  $TOOL_HOME/tools/hvigor/bin

  是否已被添加至系统 PATH 环境变量中。
• 若未配置，可手动添加路径：
  export PATH=/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH

问题二：签名配置缺失导致构建失败

错误信息：

IndexError: list index out of range

原因分析：

在

build-profile.json5

signingConfigs

解决方案：

重要提示：必须在执行构建前完成签名配置！

推荐方式 — 使用 DevEco Studio 自动配置：

1. 启动 DevEco Studio。
2. 打开对应的 Termony 项目。
3. 选择

   File → Project Structure → Signing Configs

   选项。
4. 点击

   +

   添加新的签名配置。
5. 选择

   Automatically generate signing

   （系统将自动生成测试签名）。
6. 依次点击

   Apply

   和

   OK

   完成保存操作。
7. 验证

   build-profile.json5

   中是否已成功写入签名配置。

高级用户 — 手动编辑配置文件：

• 参考“应用签名配置实战”相关章节进行设置。
• 确保所有签名文件的路径准确无误。
• 密码字段需通过

  sign.js

  进行加密处理。

验证签名配置是否生效：

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

注意事项：

• 未签名的 HAP 包可用于模拟器测试，但无法安装到真实设备上。
• 一旦配置了签名信息，构建脚本会自动对生成的 HAP 包进行签名处理。
• 签名后的 HAP 包支持在真实设备上安装运行。

问题三：HNP 包缺失

错误提示：

zip: hnp: No such file or directory

解决办法：

• 确认已经执行了

  ./create-hnp.sh

  命令以生成 HNP 包。
• 检查

  entry/hnp/arm64-v8a/

  目录是否存在且包含预期输出文件。
• 确保 HNP 包已正确复制到目标应用目录中。

问题四：构建过程中出现警告信息

警告内容：

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

说明：此类提示属于代码层面的警告，不会中断构建流程，但仍建议修复以提升代码质量。

建议改进措施：

• 增加必要的异常处理逻辑。
• 替换已弃用的旧版 API，采用官方推荐的新接口。

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

应对策略：

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

# 返回根目录并重新构建
cd ..
./build-macos.sh

构建过程优化建议

• 启用增量构建机制：
  Hvigor 工具会自动识别变更的文件，仅对改动部分进行重新编译，显著提升效率。
• 利用并行构建能力：
  Hvigor 默认启用多线程构建模式，可通过

  hvigor.properties

  调整并发线程数以匹配机器性能。
• 保留构建缓存：
  持续保留

  entry/build

  目录中的缓存数据，避免频繁清理造成重复编译开销。

构建结果验证方式

方法一：通过命令行检查输出文件

# 查看 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 | grep libentry.so

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

# 查看字体文件 Inconsolata 是否被打包
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap | grep Inconsolata

build-profile.json5

# 方法 2：分析 HAP 包的内部结构
# 进入临时目录并解压 HAP 文件
cd /tmp
unzip -q /path/to/Termony/entry/build/default/outputs/default/entry-default-unsigned.hap
tree -L 3

# 方法 1：列出未签名 HAP 包中的所有文件
unzip -l entry/build/default/outputs/default/entry-default-unsigned.hap

???? 对 HAP 包进行签名（可选步骤）
若需将应用安装至真实设备，必须对 HAP 包进行签名处理：

**步骤 1：设置签名配置**  
可在 DevEco Studio 中完成签名信息的配置，或通过手动方式修改相关配置文件。

**步骤 2：运行签名脚本**  
使用以下命令执行签名操作：
python3 sign.py \
./entry/build/default/outputs/default/entry-default-unsigned.hap \
./entry/build/default/outputs/default/entry-default-signed.hap

**步骤 3：验证签名结果**  
签名完成后，检查已生成的签名包是否存在且大小正常：
ls -lh entry/build/default/outputs/default/entry-default-signed.hap