鸿蒙应用开发实战【09】— Hvigor 构建系统与 HAP 打包全流程前言欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net开发 HarmonyOS 应用时理解构建系统是提升效率、排查问题的基础。Hvigor是华为为 HarmonyOS 定制的构建工具类似 Android 的 Gradle负责将 ArkTS 源码、资源文件编译打包成可安装的HAPHarmonyOS Ability Package。本篇从构建配置到命令行操作完整讲解号码助手的构建流程。本篇涵盖Hvigor 构建系统原理、build-profile.json5 配置、oh-package.json5 依赖管理、assembleHap 命令、增量构建、签名配置、HAP 安装部署。一、Hvigor 构建系统概述1.1 与 Gradle 的对比特性GradleAndroidHvigorHarmonyOS配置语言Groovy/Kotlin DSLTypeScripthvigorfile.ts依赖管理Maven/GradleOHPMohpm产物格式APK/AABHAP/APP增量构建✅✅缓存Gradle 缓存.hvigor/cache插件体系丰富的社区插件ohos/hvigor-ohos-plugin1.2 构建流程全图图1从源码到 HAP 的完整构建链路ArkTS 源码 (.ets) → ArkTS 编译器arkts-compiler→ JavaScript 中间码 → 方舟编译器ark-compiler → .abc 字节码 → 资源打包器 → resources.index → Hvigor 链接器 → entry-default.hap → 签名工具可选 → entry-default-signed.hap二、项目构建配置文件解析2.1 build-profile.json5 — 构建总配置// /build-profile.json5项目根 { app: { signingConfigs: [], // 签名配置列表Release 时填写 products: [ { name: default, runtimeOS: HarmonyOS, // 目标运行时纯鸿蒙 compileSdkVersion: 6.1.0.66, compatibleSdkVersion: 6.1.0.66, targetSdkVersion: 6.1.0.66, bundleType: app } ], buildModeSet: [ { name: debug }, { name: release } ] }, modules: [ { name: entry, // 模块名唯一 srcPath: ./entry, // 模块源码路径 targets: [ { name: default, applyToProducts: [default] } ] } ] }关键字段解释字段含义注意事项runtimeOS目标操作系统HarmonyOS表示纯鸿蒙不兼容 AndroidcompileSdkVersion编译时 SDK 版本与 DevEco Studio 安装的 SDK 版本一致compatibleSdkVersion最低兼容版本决定应用能在哪些系统版本上运行bundleType包类型app普通应用atomicService元服务2.2 entry/build-profile.json5 — 模块构建配置// entry/build-profile.json5 { apiType: stageMode, // 必须是 Stage 模型 buildOption: { strictMode: { caseSensitiveCheck: true // 文件名大小写敏感检查避免跨平台问题 }, arkOptions: { runtimeOnly: { sources: [] // 仅在运行时包含的 ArkTS 文件通常为空 } } }, targets: [ { name: default, runtimeOS: HarmonyOS } ] }2.3 oh-package.json5 — 依赖管理// /oh-package.json5项目根 { modelVersion: 5.0.0, name: number-assistant, version: 1.0.0, license: ISC, devDependencies: { ohos/hypium: 1.0.25 // 单元测试框架devDependency } } // entry/oh-package.json5模块级 { modelVersion: 5.0.0, name: entry, version: 1.0.0, dependencies: {} // 业务依赖目前无三方库 }三、hvigorfile.ts — 构建脚本3.1 项目根 hvigorfile.ts// hvigorfile.ts项目根import{appTasks}fromohos/hvigor-ohos-pluginexportdefault{system:appTasks,// 使用标准应用任务集plugins:[]// 无自定义插件}3.2 entry/hvigorfile.ts// entry/hvigorfile.ts模块级import{harTasks}fromohos/hvigor-ohos-pluginexportdefault{system:harTasks,// entry 使用 HAR 任务HAP 的子集plugins:[]}说明Hvigor 使用 TypeScript 编写构建脚本与 Gradle 的 Groovy/Kotlin 类似可以在构建脚本中编写自定义逻辑例如读取环境变量、条件编译等。四、命令行构建操作4.1 环境变量配置# 在终端设置 SDK 路径DevEco Studio 安装后exportDEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdkexportPATH/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH# 验证配置/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw--version4.2 常用构建命令# 进入项目目录cd/Users/fiona/Downloads/haomazhushou/app# ── 常用命令 ──# 编译 Debug HAP最常用./hvigor/bin/hvigorw assembleHap --no-daemon# 编译特定模块./hvigor/bin/hvigorw :entry:defaultassembleHap --no-daemon# 清除编译缓存./hvigor/bin/hvigorw clean --no-daemon# 查看所有可用任务./hvigor/bin/hvigorw tasks# 带详细日志./hvigor/bin/hvigorw assembleHap --no-daemon--stacktrace4.3 构建产物路径# Debug HAP 产物位置entry/build/default/outputs/default/entry-default-unsigned.hap# 查看 HAP 大小ls-lhentry/build/default/outputs/default/*.hap# 使用 zip 工具查看 HAP 内容HAP 本质是 zipunzip-lentry/build/default/outputs/default/entry-default-unsigned.hap五、增量构建与缓存机制5.1 增量构建原理Hvigor 使用任务依赖图 输入输出签名实现增量构建第一次构建编译所有 .ets 文件 → 生成 .abc 字节码 → 打包 HAP 修改一个文件后 ├── 只重新编译修改的文件 ├── 更新依赖该文件的其他文件 └── 重新打包链接阶段实测速度对比号码助手14 个页面首次构建约 20-30 秒修改 1 个页面后增量构建约 3-5 秒无修改再次构建缓存约 1-2 秒5.2 缓存目录结构.hvigor/ ├── cache/ # 增量构建缓存 │ ├── *.task-cache # 任务结果缓存 │ └── *.file-cache # 文件编译缓存 ├── outputs/ │ ├── build-logs/ │ │ └── build.log # 详细构建日志出错时必看 │ └── report/ # 构建报告 └── dependencyMap/ # 依赖关系图5.3 查看构建错误详情# 构建失败时查看详细错误cat.hvigor/outputs/build-logs/build.log|grep-EERROR|error TS# 号码助手常见错误示例# ERROR: ArkTS:ERROR File: .../HomePage.ets:505:45# Object literal must correspond to some declared class or interface# (arkts-no-untyped-obj-literals)六、Debug 与 Release 构建差异6.1 Debug 构建// Debug 构建特点 // - 不需要签名可直接安装到开发设备 // - 包含调试符号支持断点调试 // - ArkTS 编译为 JS便于调试 // - 包体较大约 3-10MB6.2 Release 构建// build-profile.json5 — 配置 Release 签名 { app: { signingConfigs: [{ name: default, type: HarmonyOS, material: { certpath: path/to/certificate.cer, // 证书文件 keyAlias: key_alias, keyPassword: 密码建议用环境变量, profile: path/to/profile.p7b, // 分发描述文件 signAlg: SHA256withECDSA, storeFile: path/to/keystore.p12, // 密钥库 storePassword: 密码 } }], products: [{ name: default, signingConfig: default // 关联签名配置 }] } }# 编译 Release HAP带签名./hvigor/bin/hvigorw assembleHap--moderelease --no-daemon七、ohpm — HarmonyOS 包管理器7.1 基本操作# ohpm 路径/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm# 安装所有依赖类似 npm installohpminstall# 安装指定包ohpminstallohos/axios# 查看已安装包ohpm list# 更新包ohpm update ohos/hypium# 配置镜像源网络问题时使用ohpm configsetregistry https://repo.harmonyos.com/ohpm/7.2 oh-package-lock.json5 — 锁定文件// oh-package-lock.json5自动生成不要手动修改 { modelVersion: 5.0.0, selfDependency: { ohos/hypium: { version: 1.0.25, resolved: https://repo.harmonyos.com/ohpm/ohos/hypium/-/ohos-hypium-1.0.25.har, integrity: sha512-..., dependencies: {} } } }八、在 DevEco Studio 中构建8.1 GUI 构建操作菜单Build → Build Hap(s)/APP(s) → Build Hap(s) ↑ Debug 构建开发用 菜单Build → Build Hap(s)/APP(s) → Build APP(s) ↑ 打 .app 包用于 AGC 上架 菜单Build → Clean Project ↑ 清除所有缓存全量重新构建8.2 快速安装到设备运行按钮▶编译 安装 启动应用 调试按钮编译 安装 启动 附加调试器 快捷键 - macOS⌘R 运行⌃D 调试 - WindowsShiftF10 运行ShiftF9 调试九、本篇小结知识点核心要点HvigorHarmonyOS 构建工具类似 Gradle用 TS 编写脚本HAPHarmonyOS Ability Package应用安装包build-profile.json5构建总配置SDK 版本、签名、模块列表oh-package.json5依赖声明文件ohpm 解析assembleHap编译打包命令–no-daemon 避免守护进程增量构建修改单文件后仅重编改动部分速度快错误排查.hvigor/outputs/build-logs/build.log参考资料鸿蒙应用开发实战【01】— 项目概述与开发环境搭建Hvigor 构建工具指南HAP 打包说明ohpm 使用指南应用签名指导build-profile.json5 配置说明DevEco Studio 构建指南AppGallery Connect 发布如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHvigor 文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-overviewohpm 包管理https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-ohpm-overview
鸿蒙应用开发实战【09】— Hvigor 构建系统与 HAP 打包全流程前言欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net开发 HarmonyOS 应用时理解构建系统是提升效率、排查问题的基础。Hvigor是华为为 HarmonyOS 定制的构建工具类似 Android 的 Gradle负责将 ArkTS 源码、资源文件编译打包成可安装的HAPHarmonyOS Ability Package。本篇从构建配置到命令行操作完整讲解号码助手的构建流程。本篇涵盖Hvigor 构建系统原理、build-profile.json5 配置、oh-package.json5 依赖管理、assembleHap 命令、增量构建、签名配置、HAP 安装部署。一、Hvigor 构建系统概述1.1 与 Gradle 的对比特性GradleAndroidHvigorHarmonyOS配置语言Groovy/Kotlin DSLTypeScripthvigorfile.ts依赖管理Maven/GradleOHPMohpm产物格式APK/AABHAP/APP增量构建✅✅缓存Gradle 缓存.hvigor/cache插件体系丰富的社区插件ohos/hvigor-ohos-plugin1.2 构建流程全图图1从源码到 HAP 的完整构建链路ArkTS 源码 (.ets) → ArkTS 编译器arkts-compiler→ JavaScript 中间码 → 方舟编译器ark-compiler → .abc 字节码 → 资源打包器 → resources.index → Hvigor 链接器 → entry-default.hap → 签名工具可选 → entry-default-signed.hap二、项目构建配置文件解析2.1 build-profile.json5 — 构建总配置// /build-profile.json5项目根 { app: { signingConfigs: [], // 签名配置列表Release 时填写 products: [ { name: default, runtimeOS: HarmonyOS, // 目标运行时纯鸿蒙 compileSdkVersion: 6.1.0.66, compatibleSdkVersion: 6.1.0.66, targetSdkVersion: 6.1.0.66, bundleType: app } ], buildModeSet: [ { name: debug }, { name: release } ] }, modules: [ { name: entry, // 模块名唯一 srcPath: ./entry, // 模块源码路径 targets: [ { name: default, applyToProducts: [default] } ] } ] }关键字段解释字段含义注意事项runtimeOS目标操作系统HarmonyOS表示纯鸿蒙不兼容 AndroidcompileSdkVersion编译时 SDK 版本与 DevEco Studio 安装的 SDK 版本一致compatibleSdkVersion最低兼容版本决定应用能在哪些系统版本上运行bundleType包类型app普通应用atomicService元服务2.2 entry/build-profile.json5 — 模块构建配置// entry/build-profile.json5 { apiType: stageMode, // 必须是 Stage 模型 buildOption: { strictMode: { caseSensitiveCheck: true // 文件名大小写敏感检查避免跨平台问题 }, arkOptions: { runtimeOnly: { sources: [] // 仅在运行时包含的 ArkTS 文件通常为空 } } }, targets: [ { name: default, runtimeOS: HarmonyOS } ] }2.3 oh-package.json5 — 依赖管理// /oh-package.json5项目根 { modelVersion: 5.0.0, name: number-assistant, version: 1.0.0, license: ISC, devDependencies: { ohos/hypium: 1.0.25 // 单元测试框架devDependency } } // entry/oh-package.json5模块级 { modelVersion: 5.0.0, name: entry, version: 1.0.0, dependencies: {} // 业务依赖目前无三方库 }三、hvigorfile.ts — 构建脚本3.1 项目根 hvigorfile.ts// hvigorfile.ts项目根import{appTasks}fromohos/hvigor-ohos-pluginexportdefault{system:appTasks,// 使用标准应用任务集plugins:[]// 无自定义插件}3.2 entry/hvigorfile.ts// entry/hvigorfile.ts模块级import{harTasks}fromohos/hvigor-ohos-pluginexportdefault{system:harTasks,// entry 使用 HAR 任务HAP 的子集plugins:[]}说明Hvigor 使用 TypeScript 编写构建脚本与 Gradle 的 Groovy/Kotlin 类似可以在构建脚本中编写自定义逻辑例如读取环境变量、条件编译等。四、命令行构建操作4.1 环境变量配置# 在终端设置 SDK 路径DevEco Studio 安装后exportDEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdkexportPATH/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH# 验证配置/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw--version4.2 常用构建命令# 进入项目目录cd/Users/fiona/Downloads/haomazhushou/app# ── 常用命令 ──# 编译 Debug HAP最常用./hvigor/bin/hvigorw assembleHap --no-daemon# 编译特定模块./hvigor/bin/hvigorw :entry:defaultassembleHap --no-daemon# 清除编译缓存./hvigor/bin/hvigorw clean --no-daemon# 查看所有可用任务./hvigor/bin/hvigorw tasks# 带详细日志./hvigor/bin/hvigorw assembleHap --no-daemon--stacktrace4.3 构建产物路径# Debug HAP 产物位置entry/build/default/outputs/default/entry-default-unsigned.hap# 查看 HAP 大小ls-lhentry/build/default/outputs/default/*.hap# 使用 zip 工具查看 HAP 内容HAP 本质是 zipunzip-lentry/build/default/outputs/default/entry-default-unsigned.hap五、增量构建与缓存机制5.1 增量构建原理Hvigor 使用任务依赖图 输入输出签名实现增量构建第一次构建编译所有 .ets 文件 → 生成 .abc 字节码 → 打包 HAP 修改一个文件后 ├── 只重新编译修改的文件 ├── 更新依赖该文件的其他文件 └── 重新打包链接阶段实测速度对比号码助手14 个页面首次构建约 20-30 秒修改 1 个页面后增量构建约 3-5 秒无修改再次构建缓存约 1-2 秒5.2 缓存目录结构.hvigor/ ├── cache/ # 增量构建缓存 │ ├── *.task-cache # 任务结果缓存 │ └── *.file-cache # 文件编译缓存 ├── outputs/ │ ├── build-logs/ │ │ └── build.log # 详细构建日志出错时必看 │ └── report/ # 构建报告 └── dependencyMap/ # 依赖关系图5.3 查看构建错误详情# 构建失败时查看详细错误cat.hvigor/outputs/build-logs/build.log|grep-EERROR|error TS# 号码助手常见错误示例# ERROR: ArkTS:ERROR File: .../HomePage.ets:505:45# Object literal must correspond to some declared class or interface# (arkts-no-untyped-obj-literals)六、Debug 与 Release 构建差异6.1 Debug 构建// Debug 构建特点 // - 不需要签名可直接安装到开发设备 // - 包含调试符号支持断点调试 // - ArkTS 编译为 JS便于调试 // - 包体较大约 3-10MB6.2 Release 构建// build-profile.json5 — 配置 Release 签名 { app: { signingConfigs: [{ name: default, type: HarmonyOS, material: { certpath: path/to/certificate.cer, // 证书文件 keyAlias: key_alias, keyPassword: 密码建议用环境变量, profile: path/to/profile.p7b, // 分发描述文件 signAlg: SHA256withECDSA, storeFile: path/to/keystore.p12, // 密钥库 storePassword: 密码 } }], products: [{ name: default, signingConfig: default // 关联签名配置 }] } }# 编译 Release HAP带签名./hvigor/bin/hvigorw assembleHap--moderelease --no-daemon七、ohpm — HarmonyOS 包管理器7.1 基本操作# ohpm 路径/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm# 安装所有依赖类似 npm installohpminstall# 安装指定包ohpminstallohos/axios# 查看已安装包ohpm list# 更新包ohpm update ohos/hypium# 配置镜像源网络问题时使用ohpm configsetregistry https://repo.harmonyos.com/ohpm/7.2 oh-package-lock.json5 — 锁定文件// oh-package-lock.json5自动生成不要手动修改 { modelVersion: 5.0.0, selfDependency: { ohos/hypium: { version: 1.0.25, resolved: https://repo.harmonyos.com/ohpm/ohos/hypium/-/ohos-hypium-1.0.25.har, integrity: sha512-..., dependencies: {} } } }八、在 DevEco Studio 中构建8.1 GUI 构建操作菜单Build → Build Hap(s)/APP(s) → Build Hap(s) ↑ Debug 构建开发用 菜单Build → Build Hap(s)/APP(s) → Build APP(s) ↑ 打 .app 包用于 AGC 上架 菜单Build → Clean Project ↑ 清除所有缓存全量重新构建8.2 快速安装到设备运行按钮▶编译 安装 启动应用 调试按钮编译 安装 启动 附加调试器 快捷键 - macOS⌘R 运行⌃D 调试 - WindowsShiftF10 运行ShiftF9 调试九、本篇小结知识点核心要点HvigorHarmonyOS 构建工具类似 Gradle用 TS 编写脚本HAPHarmonyOS Ability Package应用安装包build-profile.json5构建总配置SDK 版本、签名、模块列表oh-package.json5依赖声明文件ohpm 解析assembleHap编译打包命令–no-daemon 避免守护进程增量构建修改单文件后仅重编改动部分速度快错误排查.hvigor/outputs/build-logs/build.log参考资料鸿蒙应用开发实战【01】— 项目概述与开发环境搭建Hvigor 构建工具指南HAP 打包说明ohpm 使用指南应用签名指导build-profile.json5 配置说明DevEco Studio 构建指南AppGallery Connect 发布如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHvigor 文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-overviewohpm 包管理https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-ohpm-overview
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
