🚀 hpack - 鸿蒙 HarmonyOS 内测签名打包分发工具

🌐 官网 • 📋 更新日志 • 📚 deepwiki

</p>

简介

hpack [h-pack] 是一个专为鸿蒙 HarmonyOS 打造的内测分发工具，完成配置后，你只需一行命令，就能轻松完成鸿蒙应用的构建、签名，上传、分发、安装。

功能特性

打包签名：自动打出所有的 hap 和 hsp 包，并对它们进行签名
多 Product 支持：如果配置了多目标产物，支持选择指定的 product 打包
签名 manifest.json5：读取应用打包数据，自动生成已签名 manifest.json5 文件
分发 index 页：自动生成分发页，提供多种 HTML 模板，支持自定义模板
二维码生成：自动生成应用的二维码，方便内测人员快速下载和安装
自定义上传：支持将打包文件上传到阿里云 OSS，以及自定义上传
自定义历史打包页面：提供了 history.html 模板
webhook支持：提供了钉钉、企微、飞书等使用示例
显示设备：显示正在连接的设备 hpack targets
查看UDID：显示正在连接设备的 UDID hpack -u
签名工具：支持对未签名的 .app、.hap、.hsp 和包目录签名
命令安装：支持通过命令安装已签名的 .app、.hap 和包目录

安装使用

快速安装

pip install harmony-hpack

国内镜像源安装（推荐)

# 清华源
pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple harmony-hpack

# 阿里源
pip install -i https://mirrors.aliyun.com/pypi/simple harmony-hpack

# 腾讯源
pip install -i https://mirrors.cloud.tencent.com/pypi/simple harmony-hpack

# 官方源
pip install -i https://pypi.org/simple harmony-hpack

其他操作

# 验证安装
hpack -h

# 升级
pip install --upgrade harmony-hpack

# 卸载
pip uninstall harmony-hpack

# 配置镜像源
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

准备工作

💡 重要提示：在开始之前，建议先阅读鸿蒙官方文档 HarmonyOS 应用内部测试

你需要准备以下三个证书文件：

| 文件类型 | 格式 | 说明 | |---------|------|------| | 发布证书 | .cer | 由AGC颁发的数字证书，用于验证应用的身份和签名 | | 内部测试 Profile | .p7b | 包含了包名、数字证书信息、申请的权限列表、设备列表等信息 | | 公私钥文件 | .p12 | 包含非对称加密中使用的公钥和私钥 |

官方内部测试流程：

环境要求

| 工具 | 版本要求 | 说明 | |------|----------|------| | hvigorw、hdc | 最新版 | DevEco Studio 自带集成，也可单独安装 | | JDK | 17+ | 签名工具依赖 | | Python | 3.10+ | hpack 运行环境 |

环境检查命令：

# 检查各工具是否正确安装
java --version          # 检查 JDK 版本
python --version        # 检查 Python 版本
hvigorw -v              # 检查 hvigorw（需配置环境变量）
hdc -v                  # 检查 hdc（需配置环境变量）

⚠️ 注意：hvigorw 和 hdc 是 DevEco-Studio 自带工具，在其他终端工具下使用，需要设置环境变量，详见下方 Tips 部分。

快速开始

1、初始化项目

在项目根目录下执行初始化命令：

hpack init

初始化完成后，会生成 hpack 目录结构：

hpack/
├── config.py      # 配置文件：服务器、应用信息和打包签名等
├── Packfile.py    # 回调文件：打包完成后的自定义处理逻辑
└── sign/          # 证书目录：存放签名证书文件

2、修改配置

打开 hpack/config.py 文件，根据实际情况，修改配置信息：

class Config: 
    # 安装包存放的服务器的域名 
    DeployDomain = 'static.hpack.com'

    # 安装包存放的服务器地址，必须是 https
    BaseURL = f"https://{DeployDomain}/hpack"
    
    # 应用信息 
    AppIcon = f"{BaseURL}/AppIcon.png"
    AppName = 'hpack'
    Badge = '鸿蒙版'
    
    # index模板选择, 可选值为 [default, simple, tech, cartoon, tradition, custom]
    # 如果是 custom，则表示自定义模板，需要自己在 hpack 目录写一个 index.html，
    # 打包完成后进行内容填充，再写入 hpack/build/{product} 目录
    IndexTemplate = "default" 
    
    # 打包签名配置 
    Alias = 'your key alias'
    KeyPwd = 'your key password'
    KeystorePwd = 'your store password'
    # 替换 hapck/sign 目录下的证书文件
    SignDir = 'sign'
    Cert = os.path.join(SignDir, 'release.cer') 
    Profile = os.path.join(SignDir, 'test_release.p7b')  
    Keystore =  os.path.join(SignDir, 'harmony.p12')
  
    # 以下是 v1.0.1 新增自定义构建配置 ===================
    # 从v1.0.0升级上来的，可自行加上
    
    # 设置默认打包 product
    # 优先使用这个指定的 product。
    # 不设置，则通过读 build-prodile.json5 获取，存在多个时，打包前会提示选择
    Product = ""  
    
    # 编译模式，默认是 debug 模式，release 模式需要设置为False
    # 执行 hpack pr / hpack pd 时，这里的 Debug 配置会被命令参数覆盖
    Debug = True  
    
    # 用于完全自定义 hvigorw 构建命令，配置后 Product、Debug 无效
    # hvigorw 使用 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-commandline
    # 使用示例：
    # [
    #    'hvigorw', 'assembleHap', 'assembleHsp', 
    #    '--mode', 'module', 
    #    '-p', 'product=default', 
    #    '-p', 'debuggable=true',
    #    '--no-daemon'
    # ]
    HvigorwCommand = []

    # 历史版本按钮 - v1.0.9 新增配置
    HistoryBtn = False  # 是否显示历史版本按钮,默认不开启 Ture/False
    HistoryBtnTitle = "历史版本" # 可自定义标题
    HistoryBtnUrl = "https://github.com/iHongRen/hpack/history.html" # 历史版本页面url地址

将你的证书文件放入 hpack/sign/ 目录：

sign/
├── harmony.p12        # 公私钥文件
├── release.cer        # 发布证书  
└── test_release.p7b   # 内部测试Profile

3、开始打包

hpack p "修复了一些已知问题，优化了性能"  # 更新说明可选

新增两种强制指定打包模式的命令：

hpack pr "发版包说明"   # 强制打 release 包，忽略 hpack/config.py 中的 Debug 配置
hpack pd "调试包说明"   # 强制打 debug 包，忽略 hpack/config.py 中的 Debug 配置

✅ 打包完成后，所有打包文件将保存在 hpack/build/{product}/ 目录下。

可执行命令安装到当前连接的设备：

hpack i -[product]

📊 打包信息说明

打包完成后，PackFile.py 中的 didPack 方法会接收到详细的打包信息：

def didPack(packInfo):
    """打包完成回调，通常在这里上传打包结果到服务器"""
    print(json.dumps(packInfo, indent=4, ensure_ascii=False))

示例输出

{
    "bundle_name": "com.cxy.hpack",
    "version_code": 1000000,
    "version_name": "1.0.0",
    "debug": true,
    "size": "281KB",
    "desc": "打包说明",
    "build_dir": "hpack/build/default",
    "remote_dir": "20250605200049",
    "manifest_url": "https://服务器域名/hpack/20250605200049/manifest.json5",
    "index_url": "https://服务器域名/hpack/20250605200049/index.html",
    "product": "default",
    "date": "2025-06-05 20:00:49",
    "willPack_output": "willPack中打包前传入的参数",
    "qrcode": "data:image/svg+xml;charset=utf-8,xxx...",
}

信息字段说明

| 字段 | 类型 | 说明 | |------|------|------| | bundle_name | String | 应用包名 | | version_code | Number | 版本号 | | version_name | String | 版本名称 | | debug | Boolean | 是否为 debug 包，true / false | | size | String | 包大小 | | desc | String | 打包说明 | | build_dir | String | 本地构建目录 | | remote_dir | String | 远程目录名（时间戳） | | manifest_url | String | manifest.json5 文件 URL | | index_url | String | 分发页面 URL | | product | String | 选择的 product | | date | String | 打包时间 | | willPack_output | String | 打包前传入的参数 | | qrcode | String | 二维码 base64 数据 |

自定义上传到服务器

打包完成后，我们需要将打包文件上传到服务器，与config.py中 BaseURL一致，这样我们才能使用 Deeplink 形式安装。

def didPack(packInfo):
    """打包后回调，通常在这里上传打包结果到服务器"""
    # 打包结果在 hpack/build/{product}，编写你的上传逻辑
    pass

在项目的 custom/目录中，提供了一些上传示例，可直接复制到你的 PackFile.py 中使用：

阿里云 OSS 上传 : OSS_PackFile.py
蒲公英上传：PGY_PackFile.py
其他：欢迎 PR

运行示例

🚀 开始打包

选择 Product (多目标产物情况)

✅ 打包完成

扫码安装

自定义分发页

1、启用自定义模板 修改 config.py 文件：

IndexTemplate = 'custom'  # 启用自定义模板

2、生成模板文件 使用内置模板作为基础：

# 生成指定模板
hpack template [tname]  # 简写：hpack t tech

# 可选模板：default, simple, tech, cartoon, tradition
# 不指定则默认使用 default 模板

💡 提示：命令会在 hpack/ 目录下生成对应的 index.html 模板文件

3、配置模板处理 在 Packfile.py 中自处理定义模板，查看使用示例 custom/Index_PackFile.py

def customTemplateHtml(templateInfo):
    """_summary_: 用于生成 index.html 模板，并自定义"""
    packInfo = templateInfo.get("packInfo")
    html = templateInfo.get("html")
    
    # 填充模板变量
    template = Template(html)
    html_template = template.safe_substitute(
        app_icon=Config.AppIcon,
        title=Config.AppName,
        badge=Config.Badge,
        date=packInfo.get("date"),
        version_name=packInfo.get("version_name"),
        version_code=packInfo.get("version_code"),
        size=packInfo.get("size"),
        desc=packInfo.get("desc"),
        manifest_url=packInfo.get("manifest_url"),
        qrcode=packInfo.get("qrcode")
    )
    sys.stdout.buffer.write(html_template.encode('utf-8'))
    sys.stdout.flush()

# 调用处理函数
if __name__ == "__main__":    
    # ...省略的代码
    elif args.t:
        templateInfo = json.loads(sys.stdin.read())  
        customTemplateHtml(templateInfo)

4、执行打包

hpack p '自定义index.html'

模板预览

hpack 提供多种内置分发页模板，满足不同风格的需求：

# config.py 中配置模板
IndexTemplate = "default"  # 可选值：[default, simple, tech, cartoon, tradition, custom]

| <img src="https://raw.githubusercontent.com/iHongRen/hpack/main/screenshots/default.png" width="300"> | <img src="https://raw.githubusercontent.com/iHongRen/hpack/main/screenshots/simple.png" width="300"> | <img src="https://raw.githubusercontent.com/iHongRen/hpack/main/screenshots/tech.png" width="300"> | | :----------------------

Hpack

Install / Use

README