
阅读时长:约 19 分钟 | 难度:★★★★☆ | 篇章:第 1 篇 · 项目架构与设计哲学
对应源码:xuanxiang_ohos_app/build-profile.json5、entry/build-profile.json5、hvigorfile.ts

前言
在 HarmonyOS 应用工程化体系中,构建配置是连接源码与产物 HAP 包的关键纽带。玄象项目通过 build-profile.json5 描述签名、目标 SDK、构建模式等核心配置,通过 Hvigor 工具链执行实际的编译、打包、签名工作。本篇将深入剖析玄象项目的 build-profile.json5 配置与 Hvigor 构建链路,让您掌握从源码到上架包的完整构建链路。
提示:构建配置直接影响应用签名、设备兼容性、上架审核等关键环节。错误的构建配置会导致应用无法安装或被拒审。
一、build-profile.json5 全貌
1.1 完整配置
{
"app": {
"signingConfigs": [
{
"name": "default",
"type": "HarmonyOS",
"material": {
"certpath": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.cer",
"keyAlias": "debugKey",
"keyPassword": "0000001B5B62766726AEA7EE928A5998B9D6049FDBB6E388236DEEB59A55556BE87F1EF34B15639104916F",
"profile": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.p7b",
"signAlg": "SHA256withECDSA",
"storeFile": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.p12",
"storePassword": "0000001B1501610E1ACCAFEF6D998A406C832F71D990F24CE41683BFF7408C3C21F5F30EDC572F148D4E31"
}
}
],
"products": [
{
"name": "default",
"signingConfig": "default",
"targetSdkVersion": "6.0.2(22)",
"compatibleSdkVersion": "6.0.2(22)",
"runtimeOS": "HarmonyOS",
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true,
"useNormalizedOHMUrl": true
}
}
}
],
"buildModeSet": [
{ "name": "debug" },
{ "name": "release" }
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
}
]
}
]
}
1.2 配置结构总览
build-profile.json5 顶层字段分为三大块:
| 字段 | 作用 | 玄象配置 |
|---|---|---|
app.signingConfigs | 签名材料配置 | 1 个签名 default |
app.products | 产品定义 | 1 个产品 default |
app.buildModeSet | 构建模式 | debug + release |
modules | 模块清单 | entry 模块 |
二、signingConfigs:签名配置
2.1 玄象项目签名配置
{
"name": "default",
"type": "HarmonyOS",
"material": {
"certpath": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.cer",
"keyAlias": "debugKey",
"keyPassword": "...",
"profile": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.p7b",
"signAlg": "SHA256withECDSA",
"storeFile": "/Users/zacksleo/.ohos/config/default_xuanxiang_ohos_app_xxx.p12",
"storePassword": "..."
}
}
2.2 签名材料清单
| 字段 | 用途 | 玄象项目值 |
|---|---|---|
certpath | 证书路径 | .cer 文件 |
keyAlias | 密钥别名 | debugKey |
keyPassword | 密钥口令 | 加密字符串 |
profile | 描述文件 | .p7b 文件 |
signAlg | 签名算法 | SHA256withECDSA |
storeFile | 密钥库路径 | .p12 文件 |
storePassword | 密钥库口令 | 加密字符串 |
提示:玄象项目使用
debugKey别名,表明这是开发调试证书。生产环境必须使用发布证书(releaseKey或独立申请的企业证书)。
2.3 签名算法选择
玄象项目选用 SHA256withECDSA 签名算法,原因:
- ECDSA 比 RSA 更高效:相同安全级别下,ECDSA 签名速度更快。
- SHA-256 抗碰撞:SHA-1 已被破解,必须使用 SHA-256 及以上。
- 官方推荐:HarmonyOS AppGallery 强烈推荐 ECDSA 算法。
2.4 多签名配置策略
玄象项目当前仅有 1 个签名配置 default。规模化项目可定义多套签名:
"signingConfigs": [
{ "name": "debug", ... }, // 调试签名
{ "name": "release", ... }, // 发布签名
{ "name": "enterprise", ... } // 企业内测签名
]
三、products:产品定义
3.1 玄象项目产品配置
{
"name": "default",
"signingConfig": "default",
"targetSdkVersion": "6.0.2(22)",
"compatibleSdkVersion": "6.0.2(22)",
"runtimeOS": "HarmonyOS",
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true,
"useNormalizedOHMUrl": true
}
}
}
3.2 关键字段解析
| 字段 | 含义 | 玄象项目值 |
|---|---|---|
name | 产品名称 | default |
signingConfig | 引用的签名配置 | default |
targetSdkVersion | 目标 SDK 版本 | 6.0.2(22) |
compatibleSdkVersion | 兼容 SDK 版本 | 6.0.2(22) |
runtimeOS | 运行时操作系统 | HarmonyOS |
buildOption.strictMode | 严格模式选项 | 启用两项 |
3.3 SDK 版本规划
玄象项目当前 targetSdkVersion 与 compatibleSdkVersion 均为 6.0.2(22):
- targetSdkVersion:开发时使用的 SDK 版本,决定可用 API 集合。
- compatibleSdkVersion:运行时兼容的最低 SDK 版本,决定支持设备范围。
提示:玄象项目目前两个版本相同,意味着应用只能在 HarmonyOS 6.0.2(22) 及以上设备运行。若要兼容更低版本设备,可降低
compatibleSdkVersion。
3.4 strictMode 严格模式
玄象项目启用了两项严格模式:
"strictMode": {
"caseSensitiveCheck": true, // 大小写敏感检查
"useNormalizedOHMUrl": true // 使用规范化 OHM URL
}
caseSensitiveCheck:文件路径大小写敏感检查。macOS 默认大小写不敏感,可能导致在 Linux 服务器构建失败。启用此选项可在开发阶段提前发现问题。
useNormalizedOHMUrl:使用规范化 OHM (OpenHarmony Module) URL。这确保模块间引用路径的一致性,避免因路径格式差异导致的构建问题。
四、buildModeSet:构建模式
4.1 玄象项目构建模式
"buildModeSet": [
{ "name": "debug" },
{ "name": "release" }
]
4.2 debug 与 release 模式差异
| 维度 | debug 模式 | release 模式 |
|---|---|---|
| 代码混淆 | 不混淆 | 启用混淆 |
| 日志输出 | 全部输出 | 仅 error 级别 |
| Source Map | 包含 | 不包含 |
| 包体积 | 较大 | 较小 |
| 性能优化 | 关闭 | 启用 |
4.3 混淆配置文件
玄象项目在 entry/obfuscation-rules.txt 中定义混淆规则:
# 默认全部混淆
-enable-property-obfuscation
-enable-toplevel-obfuscation
# 保留反射使用的类名
-keep-class-name
提示:玄象项目若使用反射动态加载类,必须在混淆规则中保留对应类名,避免运行时找不到类。
五、modules:模块清单
5.1 玄象项目模块清单
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
}
]
}
]
5.2 字段含义
| 字段 | 含义 | 玄象项目值 |
|---|---|---|
name | 模块名称 | entry |
srcPath | 模块源码路径 | ./entry |
targets | 模块构建目标 | 1 个 default |
5.3 targets 与 products 的对应关系
targets[].applyToProducts 指定该构建目标适用于哪些产品:
target: default ────→ product: default
玄象项目当前是"一目标对一产品"的最简单配置。
六、Hvigor 构建工具链
6.1 Hvigor 是什么
Hvigor 是 HarmonyOS 官方构建工具,基于 Node.js 实现,提供:
- 任务调度(编译、打包、签名)
- 依赖管理(OHM 模块)
- 插件扩展机制
6.2 玄象项目 Hvigor 配置
hvigorfile.ts(工程级):
import { appTasks } from '@ohos/hvigor-ohos-plugin';
export default {
system: appTasks,
};
entry/hvigorfile.ts(模块级):
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
export default {
system: hapTasks,
};
6.3 appTasks 与 hapTasks 的区别
| 任务集 | 作用域 | 主要任务 |
|---|---|---|
appTasks | 工程级 | 构建 APP 包(多 HAP 聚合) |
hapTasks | 模块级 | 构建 HAP 包(单模块) |
6.4 Hvigor 配置文件
xuanxiang_ohos_app/
├── hvigorfile.ts # 工程级 Hvigor 脚本
├── hvigor/
│ └── hvigor-config.json5 # Hvigor 自身配置
├── entry/
│ ├── hvigorfile.ts # entry 模块 Hvigor 脚本
│ └── build-profile.json5 # entry 模块构建配置
└── build-profile.json5 # 工程级构建配置
6.5 hvigor-config.json5 详解
{
"hvigorVersion": "5.0.0",
"dependencies": {
"@ohos/hvigor-ohos-plugin": "5.0.0"
}
}
| 字段 | 含义 |
|---|---|
hvigorVersion | Hvigor 工具版本 |
dependencies | Hvigor 插件依赖 |
提示:玄象项目 Hvigor 版本应与 DevEco Studio 版本匹配。版本不匹配会导致构建失败。
七、entry/build-profile.json5 模块级配置
7.1 模块级配置示例
{
"apiType": "stageMode",
"buildOption": {
"arkOptions": {
"runtimeOnly": {
"sources": []
}
}
},
"buildModeSet": [
{
"name": "debug",
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": false
}
}
}
},
{
"name": "release",
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": true,
"files": "./obfuscation-rules.txt"
}
}
}
}
]
}
7.2 关键字段
| 字段 | 含义 | 玄象项目值 |
|---|---|---|
apiType | 应用模型 | stageMode |
buildOption.arkOptions | ArkTS 编译选项 | runtimeOnly 配置 |
buildModeSet[].arkOptions | 模式特定选项 | debug/release |
7.3 混淆规则按模式区分
玄象项目对不同构建模式采用不同混淆策略:
- debug:
obfuscation.enable = false,不混淆,便于调试。 - release:
obfuscation.enable = true,启用混淆,保护源码。
八、构建流程全貌
8.1 完整构建流程图
[hvigorw 命令]
↓
[加载 hvigorfile.ts]
↓
[执行 appTasks / hapTasks]
↓
[编译 ArkTS → Ark 字节码]
↓
[编译资源 → resources]
↓
[打包 → HAP 包]
↓
[签名 → .cer + .p7b]
↓
[输出 → build/outputs/]
8.2 玄象项目构建命令
# Debug 构建
hvigorw assembleHap --mode module -p module=entry@default -p product=default -p buildMode=debug
# Release 构建
hvigorw assembleHap --mode module -p module=entry@default -p product=default -p buildMode=release
# 构建 APP 包(上架)
hvigorw assembleApp --mode project -p product=default -p buildMode=release
8.3 构建产物结构
build/
└── outputs/
└── default/
├── entry-default-unsigned.hap # 未签名 HAP
├── entry-default-signed.hap # 已签名 HAP
└── entry-default-riched.hap # 带额外信息的 HAP
提示:玄象项目最终上架 AppGallery 的产物是
.hap(单 HAP)或.app(多 HAP 聚合)。开发者无需关心中间产物,DevEco Studio 会自动管理。
九、构建链路优化建议
9.1 增量构建
玄象项目当前全量构建耗时较长,可通过以下方式启用增量构建:
// hvigor-config.json5
{
"hvigorVersion": "5.0.0",
"dependencies": {
"@ohos/hvigor-ohos-plugin": "5.0.0"
},
"execution": {
"incremental": true // 启用增量构建
}
}
9.2 并行构建
玄象项目多模块场景下,可启用并行构建:
"execution": {
"parallel": true
}
9.3 构建缓存
"execution": {
"cache": {
"enable": true,
"path": ".hvigor/cache"
}
}
总结
本篇以玄象项目 build-profile.json5 与 Hvigor 配置为蓝本,系统剖析了 HarmonyOS 应用的构建链路:从签名配置、产品定义、构建模式、模块清单,到 Hvigor 工具链、entry 模块配置、完整构建流程,最后给出增量构建、并行构建、构建缓存的优化建议。掌握这套构建链路,是顺利推进开发、调试、发布全流程的基础。
下一篇:《09 · .ohpm 依赖管理:@ohos/hypium 与 @ohos/hamock 测试体系》,将带您深入玄象项目的依赖管理与测试体系。
如果这篇文章对你有帮助,欢迎点赞👍、收藏⭐、关注🔔,你的支持是我持续创作的动力!
相关资源:
- HarmonyOS 官方文档:构建配置文件
- HarmonyOS 官方文档:Hvigor 构建工具
- HarmonyOS 官方文档:应用签名
- HarmonyOS 官方文档:代码混淆
- 开源鸿蒙跨平台社区:https://openharmonycrossplatform.youkuaiyun.com
296



被折叠的 条评论
为什么被折叠?



