Hvigor 构建系统——从 build-profile 到 HAR 包

一、Hvigor 构建系统概述

Hvigor 是 HarmonyOS 官方的构建系统，类似于 Android 的 Gradle 或 iOS 的 Xcode Build System。它负责将 ArkTS/TS 源码、资源文件、配置文件编译打包为 HAP（HarmonyOS Ability Package）或 HAR（HarmonyOS Archive）包。

Hvigor 的核心工作流程：

1. 配置解析：读取 build-profile.json5、hvigorfile.ts 等配置文件
2. 依赖分析：解析模块间的依赖关系
3. 编译：将 ArkTS/TS 编译为方舟字节码
4. 资源打包：收集和压缩资源文件
5. 打包签名：生成 HAP/HAR 包并进行签名

二、build-profile.json5 11 模块配置

在根目录的 build-profile.json5 中，配置了应用级别的构建参数，包括所有 11 个模块的注册：

{
  "app": {
    "signingConfigs": [...],
    "products": [...],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    { "name": "entry", "srcPath": "./product/entry", "targets": [...] },
    { "name": "homePage", "srcPath": "./features/homePage" },
    { "name": "minePage", "srcPath": "./features/minePage" },
    { "name": "topicPage", "srcPath": "./features/topicPage" },
    { "name": "commonLib", "srcPath": "./commons/commonLib" },
    { "name": "base_select", "srcPath": "./components/base_select" },
    { "name": "select_category", "srcPath": "./components/select_category" },
    { "name": "answer_questions", "srcPath": "./components/answer_questions" },
    { "name": "login_info", "srcPath": "./components/login_info" },
    { "name": "aggregated_payment", "srcPath": "./components/aggregated_payment" },
    { "name": "feedback", "srcPath": "./components/feedback" },
    { "name": "search", "srcPath": "./components/search" },
    { "name": "search_question", "srcPath": "./components/search_question" }
  ]
}

总共 13 个模块注册项，其中 entry 模块有 targets 配置（指定应用到的产品），其他模块共享默认配置。

模块架构分类：

• product 层：entry——应用入口和主配置
• features 层：homePage、minePage、topicPage——业务功能模块
• commons 层：commonLib——公共组件、工具、模型
• components 层：base_select、select_category 等 9 个业务组件

三、hvigorfile.ts 的作用

每个模块都有自己的 hvigorfile.ts：

// 根 hvigorfile.ts
import { appTasks } from '@ohos/hvigor-ohos-plugin';
export default {
  system: appTasks,
  plugins: []
};

// 模块 hvigorfile.ts（以 commonLib 为例）
import { harTasks } from '@ohos/hvigor-ohos-plugin';
export default {
  system: harTasks,    // HAR 模块使用 harTasks
  plugins: []
};

hvigorfile.ts 的关键配置：

• system：指定模块类型。harTasks 用于 HAR 模块，hapTasks 用于 HAP 模块（如 entry）
• plugins：配置插件。可以集成自定义插件（如代码分析插件、自定义打包任务）

对于 commonLib 这样的库模块，使用 harTasks；对于 entry 这样的应用模块，使用 hapTasks。

四、HAR 包的构建过程

HAR（HarmonyOS Archive）包是 HarmonyOS 的静态共享包。构建 HAR 包的过程：

1. 源码编译：将模块内的 ArkTS/TS 源码编译为方舟字节码
2. 资源收集：收集模块的 resources 目录下的资源文件
3. 索引生成：生成模块的 Index.ets，定义对外暴露的接口
4. 打包：将编译产物、资源、配置打包为 .har 文件

HAR 包的产物位于：

commons/commonLib/build/default/outputs/default/commonLib.har

HAR 包可以被其他模块通过 oh-package.json5 的依赖声明引用：

// entry 的 oh-package.json5
{
  "dependencies": {
    "commonlib": "file:../../commons/commonLib"
  }
}

五、模块间的编译顺序

Hvigor 会根据模块依赖关系确定编译顺序。在 11 模块架构中，典型的依赖关系是：

commonLib (最底层，先编译)
  ├── homePage
  ├── minePage
  ├── topicPage
  ├── base_select
  ├── select_category
  ├── answer_questions
  ├── login_info
  ├── aggregated_payment
  ├── feedback
  ├── search
  ├── search_question
  └── entry (最上层，最后编译，依赖所有模块)

Hvigor 的依赖解析器会自动分析 oh-package.json5 中的依赖声明，构建依赖图，然后按拓扑序编译。如果存在循环依赖，构建会失败。

六、Hvigor 构建缓存与优化

Hvigor 提供了多种构建优化机制：

1. 增量编译：只重新编译发生变化的文件，利用 .hvigor/cache/ 中的缓存信息
2. 并行编译：无依赖关系的模块可以并行编译（如所有 features 和 components 模块）
3. 缓存复用：相同的输入文件产生相同的编译输出，缓存命中时跳过编译

七、总结

Hvigor 是 HarmonyOS 构建体系的基石。在 11 模块的英语学习 App 中，build-profile.json5 定义了 13 个模块的层次结构，hvigorfile.ts 配置了每个模块的构建类型（HAP/HAR），依赖关系决定了编译顺序。commonLib 作为最底层模块，先被编译为 HAR 包，然后被其他 feature 和 component 模块引用。理解 Hvigor 的工作机制，对于解决构建问题、优化构建速度很有帮助。