HarmonyOS7 工程化：hvigor 构建与多模块拆分配置

前言

项目小的时候，所有代码塞一个entry模块没问题。但等项目变大、多人协作、要复用组件库，就必须做模块化拆分。

HarmonyOS 用hvigor（基于 TS 的构建工具，类似前端的 Gradle/Webpack）管理构建和模块。这篇文章讲清：hvigor 是干嘛的、模块怎么拆（HAR/HSP）、多模块工程怎么配置。

hvigor 是什么

hvigor是鸿蒙的构建引擎，负责把你的 ArkTS 代码编译、打包成 app。你平时点 DevEco 的"运行"按钮，背后就是它在干活。

工程根目录的关键文件：

代码实现

project/ ├── build-profile.json5 # 工程级构建配置（签名、设备类型） ├── hvigorfile.ts # 根构建脚本 ├── entry/ # 主模块 │ └── hvigorfile.ts └── library/ # 共享库模块 └── hvigorfile.ts

每个模块都有自己的hvigorfile.ts，决定它是"应用模块"还是"库模块"。

模块类型：HAP / HAR / HSP

记忆法：HAP 是"能跑的 app 模块"；HAR 是"打包时复制的库"（每个引用方都留一份）；HSP 是"运行时共享的库"（多模块共用一份，省包体）。

新建一个 HAR 库模块

把通用组件、工具函数抽到 HAR，供多个业务模块复用：

核心代码

// library/index.ets 导出的公共能力exportclassDateUtil{staticformat(ts:number):string{returnnewDate(ts).toLocaleString()}}exportconstCOLORS={primary:'#4A90E2'}

在library/hvigorfile.ts里声明它是 HAR：

完整示例

import{harTasks}from'@ohos/hvigor-ohos-plugin'exportdefault{system:harTasks,// 标记为 HAR 库plugins:[]}

主模块引用库

在entry/oh-package.json5里依赖这个库：

代码解析

{ "dependencies": { "mylibrary": "file:../library" } }

然后代码里直接 import 用：

实现拆解

import{DateUtil,COLORS}from'mylibrary'Text(DateUtil.format(Date.now())).fontColor(COLORS.primary)

多模块构建配置

build-profile.json5里声明产品形态和签名：

代码清单

{ "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [{ "name": "default" }] }, { "name": "library", "srcPath": "./library" } ], "app": { "signingConfigs": [{ "name": "default", "material": { /* 签名文件 */ } }], "products": [{ "name": "default", "signingConfig": "default" }] } }

拆分的经验法则

• 通用 UI 组件、工具类 → 抽HAR（如uicomponents、utils）。
• 多个 HAP 都要用的"大块功能"（如分享、登录）→ 抽HSP，省包体。
• 业务逻辑独立、可单独上架 → 抽HAP（feature 模块）。
• 模块之间禁止循环依赖（A 依赖 B，B 不能又依赖 A）。

常见误区（小白必踩）

下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲，改一改文末「动手改一改」里的参数，亲眼看看效果。

完整可运行示例：hvigor 多模块配置

在build-profile.json5里拆出独立feature模块。

关键代码

// build-profile.json5（节选） { "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [{ "name": "default" }] }, { "name": "feature_home", "srcPath": "./feature_home", "targets": [{ "name": "default" }] } ] }

你会看到什么：entry是主模块，feature_home是独立业务模块。编译后各模块可单独构建、按需加载，大项目协作不再互相阻塞。

动手改一改：

• 新建feature_cart模块并在modules注册，体验增量编译。
• 在oh-package.json5里把公共库抽成 HAR 依赖。
• 用hvigorw assembleHap只构建指定模块，看速度提升。

写在最后

工程化前期麻烦，后期省命。模块拆分的核心判断是：这段代码会不会在别处复用？会，就抽库（HAR/HSP）；业务独立，就拆 HAP。

别等项目烂到改一处崩三处才想起重构。现在就看看你的entry里有没有"明显通用"的组件，先抽一个 HAR 出来练手——模块化思维一旦建立，后面越写越顺。