阅读时长约 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 个签名defaultapp.products产品定义1 个产品defaultapp.buildModeSet构建模式debugreleasemodules模块清单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密钥别名debugKeykeyPassword密钥口令加密字符串profile描述文件.p7b文件signAlg签名算法SHA256withECDSAstoreFile密钥库路径.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产品名称defaultsigningConfig引用的签名配置defaulttargetSdkVersion目标 SDK 版本6.0.2(22)compatibleSdkVersion兼容 SDK 版本6.0.2(22)runtimeOS运行时操作系统HarmonyOSbuildOption.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模块名称entrysrcPath模块源码路径./entrytargets模块构建目标1 个default5.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}fromohos/hvigor-ohos-plugin;exportdefault{system:appTasks,};entry/hvigorfile.ts模块级import{hapTasks}fromohos/hvigor-ohos-plugin;exportdefault{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 } }字段含义hvigorVersionHvigor 工具版本dependenciesHvigor 插件依赖提示玄象项目 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应用模型stageModebuildOption.arkOptionsArkTS 编译选项runtimeOnly 配置buildModeSet[].arkOptions模式特定选项debug/release7.3 混淆规则按模式区分玄象项目对不同构建模式采用不同混淆策略debugobfuscation.enable false不混淆便于调试。releaseobfuscation.enable true启用混淆保护源码。八、构建流程全貌8.1 完整构建流程图[hvigorw 命令] ↓ [加载 hvigorfile.ts] ↓ [执行 appTasks / hapTasks] ↓ [编译 ArkTS → Ark 字节码] ↓ [编译资源 → resources] ↓ [打包 → HAP 包] ↓ [签名 → .cer .p7b] ↓ [输出 → build/outputs/]8.2 玄象项目构建命令# Debug 构建hvigorw assembleHap--modemodule-pmoduleentrydefault-pproductdefault-pbuildModedebug# Release 构建hvigorw assembleHap--modemodule-pmoduleentrydefault-pproductdefault-pbuildModerelease# 构建 APP 包上架hvigorw assembleApp--modeproject-pproductdefault-pbuildModerelease8.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.csdn.net