🌐 官网 • 📋 更新日志 • 📚 deepwiki
hpack [h-pack] 是一个专为鸿蒙 HarmonyOS 打造的内测分发工具，完成配置后，你只需一行命令，就能轻松完成鸿蒙应用的构建、签名，上传、分发、安装。
- 📦 打包签名：自动打出所有的
hap和hsp包，并对它们进行签名 - 🎯多 Product 支持：如果配置了多目标产物，支持选择指定的
product打包 - 📝 签名 manifest.json5：读取应用打包数据，自动生成已签名
manifest.json5文件 - 🌐 分发 index 页：自动生成分发页，提供多种 HTML 模板，支持自定义模板
- 📱 二维码生成：自动生成应用的二维码，方便内测人员快速下载和安装
- ☁️ OSS 上传：支持将打包文件上传到阿里云 OSS，以及自定义上传
- 📱 显示设备：显示正在连接的设备
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 部分。
在项目根目录下执行初始化命令：
hpack init初始化完成后，会生成 hpack 目录结构：
hpack/
├── config.py # 配置文件：服务器、应用信息和打包签名等
├── Packfile.py # 回调文件：打包完成后的自定义处理逻辑
└── sign/ # 证书目录：存放签名证书文件
打开 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
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 = []替换证书文件
将你的证书文件放入 hpack/sign/ 目录：
sign/
├── harmony.p12 # 公私钥文件
├── release.cer # 发布证书
└── test_release.p7b # 内部测试Profile
执行打包命令，可选择性地添加更新说明：
# 完整命令
hpack pack "修复了一些已知问题，优化了性能"
# 简写形式
hpack p "更新说明"✅ 打包完成后，所有文件将保存在 hpack/build/{product}/ 目录下。
☁️ 阿里云 OSS 上传配置
安装依赖： ```bash pip3 install oss2
**配置 OSS：**
打开 `Packfile.py` 完成配置：
```python
class OSSConfig:
# OSS 配置信息
Access_key_id = 'your_access_key_id'
Access_key_secret = 'your_access_key_secret'
Endpoint = 'your_endpoint'
Bucket_name = 'your_bucket_name'
Bucket_dir = 'hpack'
⚒️ 自定义服务器上传
如果使用其他服务器，需要在didPack中编写上传代码：
def didPack(packInfo):
"""打包后回调，通常在这里上传打包结果到服务器"""
# 打包结果在 hpack/build/{product}，编写你的上传逻辑
pass
📖 查看帮助
hpack -h # 或 hpack help命令分类：
| 命令 | 说明 |
|---|---|
hpack -v, --version |
显示版本信息 |
hpack -h, --help |
显示帮助信息 |
hpack -u, --udid |
显示设备的 UDID |
hpack targets |
显示连接的设备列表 |
| 命令 | 说明 |
|---|---|
hpack init |
初始化 hpack 目录并创建配置文件 |
hpack pack, p [desc] |
执行打包签名和上传，desc 为打包描述（可选） |
hpack template, t [tname] |
生成 index.html 模板文件 |
📱 安装命令
# 安装指定 product 的产物
hpack i -myproduct # 注意加上横杠(-)# 安装 .app 文件
hpack i ./xx.app
# 安装 .hap 文件
hpack i ./xx.hap
# 安装目录下所有包
hpack i ./build/default✍️ 签名命令
hpack sign,s <unsignedPath> <certPath># 签名 .app 文件
hpack s ./xx.app ./sign/cert.py
# 签名 .hap 文件
hpack s ./xx.hap ./sign/cert.py
# 签名目录
hpack s ./build/default ./sign/cert.pysign/
├── cert.py # 签名配置文件
├── certFile.cer # 证书文件
├── keystore.p12 # 公私钥文件
└── profile.p7b # Profile 文件
# -*- coding: utf-8 -*-
Alias = 'key alias'
KeyPwd = 'key password'
KeystorePwd = 'store password'
Cert = './certFile.cer' # 相对于cert.py的路径
Profile = './profile.p7b' # 相对于cert.py的路径
Keystore = './keystore.p12' # 相对于cert.py的路径hpack 提供多种内置分发页模板，满足不同风格的需求：
# config.py 中配置模板
IndexTemplate = "default" # 可选值：[default, simple, tech, cartoon, tradition, custom] |
 |
 |
|---|---|---|
| default 默认风格 | simple 简单 | tech 科技 |
 |
 |
|---|---|
| cartoon 卡通 | tradition 传统 |
修改 config.py 文件：
IndexTemplate = 'custom' # 启用自定义模板使用内置模板作为基础：
# 生成指定模板
hpack template [tname] # 简写：hpack t tech
# 可选模板：default, simple, tech, cartoon, tradition
# 不指定则默认使用 default 模板💡 提示：命令会在
hpack/目录下生成对应的index.html模板文件
在 Packfile.py 中启用自定义模板处理：
def customTemplateHtml(templateInfo):
packInfo = templateInfo["packInfo"]
html = templateInfo["html"]
date = datetime.now().strftime("%Y-%m-%d %H:%M")
# 填充模板变量
template = Template(html)
html_template = template.safe_substitute(
app_icon=Config.AppIcon,
title=Config.AppName,
badge=Config.Badge,
date=date,
version_name=packInfo["version_name"],
version_code=packInfo["version_code"],
size=packInfo["size"],
desc=packInfo["desc"],
manifest_url=packInfo["manifest_url"],
qrcode=packInfo["qrcode"]
)
print(html_template) # ⚠️ 不可删除，用于传参
# 调用处理函数
if __name__ == "__main__":
# ...省略的代码
elif args.t:
templateInfo = json.loads(sys.stdin.read())
customTemplateHtml(templateInfo) hpack p '自定义index.html'打包完成后，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",
"size": "281KB",
"desc": "打包说明",
"build_dir": "hpack/build/default",
"remote_dir": "20250605200049",
"manifest_url": "https://服务器域名/hpack/20250605200049/manifest.json5",
"qrcode": "data:image/svg+xml;charset=utf-8,xxx...",
"index_url": "https://服务器域名/hpack/20250605200049/index.html",
"product": "default",
"willPack_output": "willPack中打包前传入的参数"
}| 字段 | 类型 | 说明 |
|---|---|---|
bundle_name |
String | 应用包名 |
version_code |
Number | 版本号 |
version_name |
String | 版本名称 |
size |
String | 包大小 |
desc |
String | 打包说明 |
build_dir |
String | 本地构建目录 |
remote_dir |
String | 远程目录名（时间戳） |
manifest_url |
String | manifest.json5 文件 URL |
qrcode |
String | 二维码 base64 数据 |
index_url |
String | 分发页面 URL |
product |
String | 选择的 product |
willPack_output |
String | 打包前传入的参数 |
🔧 环境配置
在非 DevEco-Studio 终端中使用时需要配置：
# macOS
# .zshrc 文件
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
# 验证配置
hvigorw -v
# Windows
# 参考官方文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-commandline在 .gitignore 文件中添加：
# 忽略 Python 临时文件
__pycache__/⚠️ 常见问题
- 证书不一致：如果已安装的 App 和准备安装的 App 打包证书不一致，需先卸载已安装的 App
- Profile 类型：
- 使用调试.p7b：只能本地命令安装
- 使用内部测试 Profile.p7b：才能通过 DeepLink (链接) 形式安装
- 联网校验：安装时鸿蒙会进行联网校验，如果验证失败，尝试关闭代理
- 错误码：安装出错时会有提示，可根据 错误码说明 查找原因
如果 hpack 对你有帮助，请考虑：
- ⭐ 给项目点个 Star
- 🔄 分享给更多开发者
- 💬 在社区中推荐使用