鸿蒙应用开发实战【09】— Hvigor 构建系统与 HAP 打包全流程

前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
在这里插入图片描述

开发 HarmonyOS 应用时，理解构建系统是提升效率、排查问题的基础。Hvigor 是华为为 HarmonyOS 定制的构建工具，类似 Android 的 Gradle，负责将 ArkTS 源码、资源文件编译打包成可安装的 HAP（HarmonyOS Ability Package）。本篇从构建配置到命令行操作，完整讲解号码助手的构建流程。

本篇涵盖：Hvigor 构建系统原理、build-profile.json5 配置、oh-package.json5 依赖管理、assembleHap 命令、增量构建、签名配置、HAP 安装部署。

一、Hvigor 构建系统概述

1.1 与 Gradle 的对比

特性 Gradle（Android） Hvigor（HarmonyOS）
配置语言 Groovy/Kotlin DSL TypeScript（hvigorfile.ts）
依赖管理 Maven/Gradle OHPM（ohpm）
产物格式 APK/AAB HAP/APP
增量构建 ✅ ✅
缓存 Gradle 缓存 .hvigor/cache
插件体系 丰富的社区插件 @ohos/hvigor-ohos-plugin

1.2 构建流程全图

Hvigor 构建流程

图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" 表示纯鸿蒙，不兼容 Android
compileSdkVersion 编译时 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 } from '@ohos/hvigor-ohos-plugin'

export default {
  system: appTasks,   // 使用标准应用任务集
  plugins: []         // 无自定义插件
}

3.2 entry/hvigorfile.ts

// entry/hvigorfile.ts（模块级）
import { harTasks } from '@ohos/hvigor-ohos-plugin'

export default {
  system: harTasks,   // entry 使用 HAR 任务（HAP 的子集）
  plugins: []
}

说明：Hvigor 使用 TypeScript 编写构建脚本（与 Gradle 的 Groovy/Kotlin 类似），可以在构建脚本中编写自定义逻辑，例如读取环境变量、条件编译等。

四、命令行构建操作

4.1 环境变量配置

# 在终端设置 SDK 路径（DevEco Studio 安装后）
export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH"

# 验证配置
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw --version

4.2 常用构建命令

# 进入项目目录
cd /Users/fiona/Downloads/haomazhushou/app

# ── 常用命令 ──

# 编译 Debug HAP（最常用）
./hvigor/bin/hvigorw assembleHap --no-daemon

# 编译特定模块
./hvigor/bin/hvigorw :entry:default@assembleHap --no-daemon

# 清除编译缓存
./hvigor/bin/hvigorw clean --no-daemon

# 查看所有可用任务
./hvigor/bin/hvigorw tasks

# 带详细日志
./hvigor/bin/hvigorw assembleHap --no-daemon --stacktrace

4.3 构建产物路径

# Debug HAP 产物位置
entry/build/default/outputs/default/entry-default-unsigned.hap

# 查看 HAP 大小
ls -lh entry/build/default/outputs/default/*.hap

# 使用 zip 工具查看 HAP 内容（HAP 本质是 zip）
unzip -l entry/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 -E "ERROR|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-10MB）

6.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 --mode release --no-daemon

七、ohpm — HarmonyOS 包管理器

7.1 基本操作

# ohpm 路径
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm

# 安装所有依赖（类似 npm install）
ohpm install

# 安装指定包
ohpm install @ohos/axios

# 查看已安装包
ohpm list

# 更新包
ohpm update @ohos/hypium

# 配置镜像源（网络问题时使用）
ohpm config set registry 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 调试
- Windows：Shift+F10 运行，Shift+F9 调试

九、本篇小结

知识点 核心要点
Hvigor HarmonyOS 构建工具，类似 Gradle，用 TS 编写脚本
HAP HarmonyOS Ability Package，应用安装包
build-profile.json5 构建总配置：SDK 版本、签名、模块列表
oh-package.json5 依赖声明文件，ohpm 解析
assembleHap 编译打包命令，–no-daemon 避免守护进程
增量构建 修改单文件后仅重编改动部分，速度快
错误排查 .hvigor/outputs/build-logs/build.log

参考资料

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# harmonyos # 华为 # 鸿蒙系统
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

鸿蒙应用开发实战【07】— ArkUI 状态管理全解析（@State/@Prop/@Link/@Watch）

avatar 人工智能6S服务平台
cover

鸿蒙原生 ArkTS 布局深度解析：ColumnStart 顶部起始分布模式（API 24）

avatar 人工智能6S服务平台
cover

鸿蒙应用开发实战【06】— 应用入口与生命周期管理（EntryAbility 深度解析）

avatar 人工智能6S服务平台