hvigor 构建体系:把"本地能跑 CI 不能跑"拆开看
有个现象在鸿蒙工程里出现得特别勤:代码在你机器上编得好好的,推到 CI 上第一步就红。
我第一次遇到这个是在 2025 年底,报错原文是 Cannot find hvigor version 5.0.2 in dependencies。当时我的第一反应是 CI 机器没装 SDK,查了半小时才发现,是 hvigor-config.json5 里的 modelVersion 写着 IDE 升级前的旧值。
这类问题的共同点是:它不在你的代码里。所以先学会读构建配置,比学会写业务代码更能救急。
学之前先知道要交什么
四件事,学完能独立完成:
- 说清
hvigorw为什么是唯一合法入口,以及绕过它会付出什么代价。 - 拿到一个陌生工程,五分钟内判断出某个配置项该写在哪一份文件里。
- 面对"拆成 HAP 还是 HSP"的争论,能按三条判断顺序当场给出结论。
- 在 CI 上跑通一条包含构建、签名、混淆、符号表归档的流水线,并说清每一步失败时的排查方向。
基线先钉住:HarmonyOS 6.0.0(API 20,2025 年 9 月 25 日 Release)配套 DevEco Studio 6.0.0 与 hvigor;截至 2026 年 11 月,更高版本的构建行为差异我没逐一验证过,本文只对这条基线负责。这里有个和 Gradle、Maven 都不一样的设定——hvigor 的版本号与 IDE 绑定,modelVersion 填错直接构建失败,后面第四节专门讲。构建配置各字段的权威说明在 HarmonyOS 开发者文档中心 的构建分区。
提前记住一句话
modelVersion 不是"我想用哪个版本",是"我的 IDE 是哪个版本"。这个认知差别是新手最容易掉进去的坑。
坐标系:四层结构一目了然
这张图里有个因果关系值得停一下:任务名是模块类型注册出来的,不是命令行决定的。
所以你在一个 HAR 模块目录下敲 hvigorw assembleHap,会得到一个 Task 'assembleHap' not found。不是权限问题,不是参数写错,是这个模块的 hvigorfile.ts 里注册的是 harTasks,任务图里压根没这个节点。
任务图与 wrapper:谁在决定能跑什么
定义:hvigor 是跑在 Node.js 上的构建框架,构建逻辑用 TypeScript 写成 task,按依赖关系编排成有向无环图。hvigorw 是它的 wrapper,负责读 modelVersion、准备对应版本的 hvigor 本体、再用同一套参数执行任务。
反例:直接 node ./node_modules/@ohos/hvigor/bin/hvigor.js assembleHap。这行命令能跑通,但它绕过了版本校验——本地和服务器用的可能不是同一个构建器,而你不会收到任何提示。
模块级的 hvigorfile.ts 只有三行有用,但这一行决定了整个模块能执行什么任务:
// entry/hvigorfile.ts —— HAP 模块
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
export default {
system: hapTasks, // HAR 模块换成 harTasks,HSP 模块换成 hspTasks
plugins: []
};改这一行之前先看模块类型
system 字段写错模块类型,任务图会注册出一批当前模块用不上的任务,表现是"任务能跑但产出的包不对"。改之前先确认 module.json5 里的 type 字段。
三份文件,各管一件事
新手最常问的不是"怎么写",是"这个配置该放哪"。实际上真正起作用的只有三份(严格说是四份,因为 build-profile.json5 有工程级和模块级两份)。
| 文件 | 作用域 | 决定什么 | 该由谁维护 |
|---|---|---|---|
build-profile.json5(工程级) | 整个 App | 打包成什么、用哪套签名、包含哪些模块 | 主要交给 IDE,手改 modules 要同步 srcPath |
build-profile.json5(模块级) | 单个模块 | 这个模块怎么编:API 类型、混淆、编译目标 | 混淆规则必须手写 |
oh-package.json5 | 模块或工程 | 依赖谁、什么版本 | 改完必须提交 oh-package-lock.json5 |
hvigor-config.json5 | 整个工程 | 用哪个版本的 hvigor、构建行为 | 只改 execution 与 nodeOptions |
// hvigor-config.json5 —— 工程根目录
{
"modelVersion": "6.0.0", // 跟随 DevEco Studio 主版本,IDE 新建工程自动写入
"dependencies": {},
"execution": {
"daemon": true, // 本地 true;CI 上用 --no-daemon 覆盖
"incremental": true,
"parallel": true
},
"logging": { "level": "info" },
"nodeOptions": {
"maxOldSpaceSize": 8192 // 大工程编译 ArkTS 容易 OOM,按机器内存给
}
}// build-profile.json5(工程级)—— 节选:产物、签名、模块清单
{
"app": {
"signingConfigs": [{
"name": "release",
"type": "HarmonyOS",
"material": {
"storeFile": "./signature/release.p12",
"storePassword": "<CI 注入>", // CI 用环境变量注入,绝不提交明文
"keyAlias": "releaseKey",
"keyPassword": "<CI 注入>",
"certpath": "./signature/release.cer",
"profile": "./signature/release.p7b",
"signAlg": "SHA256withECDSA"
}
}],
"products": [{
"name": "default",
"signingConfig": "release",
"compatibleSdkVersion": "6.0.0(20)",
"runtimeOS": "HarmonyOS"
}]
},
"modules": [
{ "name": "entry", "srcPath": "./entry",
"targets": [{ "name": "default", "applyToProducts": ["default"] }] },
{ "name": "shared", "srcPath": "./shared" }
]
}混淆的入口在模块级,apiType 固定写 stageMode(FA 模型已经不推荐了):
// shared/build-profile.json5 —— 节选
{
"apiType": "stageMode",
"buildOptionSet": [{
"name": "release",
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": true,
"files": ["./obfuscation-rules.txt"]
},
"consumerFiles": ["./consumer-rules.txt"] // 给依赖方继承的保留规则
}
}
}]
}consumerFiles 是 HAR/HSP 作者最该写却最常漏的一项。库里的类名被混淆后,调用方按名字反射就会崩。作者把"必须保留的名字"写进 consumer-rules.txt,依赖方不用知情也能正确构建。
拆模块:三个产物的本质差别
定义上的差别不在目录结构,在运行时被复制几份、编译期被链接几次。
| 类型 | 产物 | 能否含 UIAbility | 运行时实例 | 典型用途 |
|---|---|---|---|---|
| HAP | .hap | 能 | 每个 HAP 独立 | 应用入口、可独立跳转的功能 |
| HSP | .hsp | 能 | 同进程多 HAP 共享一份 | 多 HAP 共用的 UI 与状态 |
| HAR | .har | 不能 | 静态链接,复制进每个引用方 | 纯逻辑库、工具函数、无状态组件 |
判断顺序照着走,三条就够:
一,需要独立入口或被其他应用拉起?是 → HAP。
二,会被两个以上 HAP 引用,且体积或状态共享有意义?是 → HSP。
三,其余情况 → HAR。
第三条要克制。HAR 最省心,但它会被复制:一个 2MB 的 HAR 被 3 个 HAP 引用,安装包就多 6MB。HSP 是独立打包、运行时加载,多 HAP 共享同一份实例;代价是加载时机不可控,首次调用有一次加载耗时,而且 HSP 必须和宿主应用一起签名分发。
依赖方向必须单向:entry(HAP) → feature(HAP) → shared(HSP) → common(HAR)。反过来(HAR 引 HSP)在 hvigor 里直接报循环依赖或模块类型不匹配。要解耦就把事件往上抛、用路由跳转,别让底层知道上层。
这条方向约束在真实工程里最容易破的地方是"工具类库想复用一层网络封装"。common 里为了少写几行,import 了 shared 里那个带 UI 的请求组件,编译立刻拒绝。正确的做法是把纯逻辑再往下沉一层,或者让 shared 反向暴露一个接口,由 common 依赖接口——说起来简单,改起来是一整轮重构。
所以拆模块这件事,最好在工程只有三个模块的时候就想清楚层级,别等到十五个模块再来补。
版本对齐:三处错一处,就只有一台机器能编
这三处必须同时对齐:
modelVersion 对 IDE 主版本。它决定 hvigor 用哪套构建模型,写一个不存在的版本,hvigorw 在准备阶段就失败。
compatibleSdkVersion 对目标设备。写 6.0.0(20) 表示最低兼容 API 20。调低能覆盖更多设备,但用到 20 才有的 API 时编译不报错、运行崩,得用 canIUse 之类的运行时判断兜底。
oh-package.json5 对 oh-package-lock.json5。依赖写成 ^1.2.0,本地和 CI 完全可能装到不同小版本。lock 文件必须进版本库。
这里给一个明确判断:我不建议为了"统一"把团队所有人的 modelVersion 手动锁在某个旧值上。 看起来整齐,实际是把新 IDE 的新特性全部关掉,而且半年后没人记得为什么锁着。要统一就统一 IDE 版本,别统一配置文件。
工程根的 oh-package.json5 里可以用 overrides 强制统一传递依赖的版本,这是解决"两个库各自依赖不同版本的同一个工具库"的标准手段。私有仓库在 .ohpmrc 里配 registry,token 走环境变量。
有一处只有真正在 CI 上排过障的人才会注意:ohpm install --all 和 ohpm install 在 lock 存在时的行为差异,会在"有人本地跑过一次 ohpm update"之后暴露出来。那次 update 会改 lock 文件,如果被一起提交,CI 装到的版本就全变了,而构建依然成功——问题要等到线上崩溃栈对不上符号表才出现。
顺便把增量的账也算一下。本地开发保持 daemon: true,复用 Node 进程,第二次构建明显更快;CI 上建议 --no-daemon,避免构建进程残留导致任务挂住不退出。这一条我吃过两次亏,第二次是因为流水线里有个步骤超时中断,守护进程留在后台,下一次构建就卡在等锁上,日志里一个字都不打。
排查这类"卡住不退出"的问题,先看机器上有没有残留的 hvigor 进程,再去看 yml 里的超时设置。别去读业务代码,跟它无关。
动手:一条能跑在 CI 上的流水线
CI 环境只需要一套 HarmonyOS Command Line Tools(含 hvigorw、ohpm、hdc 与 SDK),关键是 DEVECO_SDK_HOME 指向 SDK 根目录。
#!/usr/bin/env bash
set -euo pipefail
# 前提:Command Line Tools 版本与 DevEco Studio 6.0.0 对齐
export DEVECO_SDK_HOME=/opt/commandline-tools/sdk
export PATH="/opt/commandline-tools/bin:$PATH" # 含 hvigorw / ohpm / hdc
# 1. versionCode 由流水线写入,不依赖人工改
node -e "
const fs=require('fs');
const p='AppScope/app.json5';
let s=fs.readFileSync(p,'utf8');
s=s.replace(/\"versionCode\":\s*\d+/, '\"versionCode\": ' + (process.env.BUILD_NUMBER||1));
fs.writeFileSync(p,s);
"
# 2. 按 lock 安装依赖,不要用会重新解析版本的命令
ohpm install --all
# 3. 构建 release HAP;--no-daemon 避免 CI 上进程残留
./hvigorw --mode module \
-p product=default \
-p module=entry@default \
-p buildMode=release \
assembleHap --no-daemon
# 4. 归档产物与符号表
mkdir -p artifacts
cp entry/build/default/outputs/default/*-signed.hap artifacts/
cp entry/build/default/outputs/default/nameCache.json artifacts/ 2>/dev/null || true第 4 步那个 nameCache.json 是 release 混淆的副产物,靠混淆规则里的 -print-namecache 生成:
# entry/obfuscation-rules.txt
-enable-property-obfuscation # 收益最大,也最容易踩反射
-enable-toplevel-obfuscation # 混淆顶层作用域名称
-enable-filename-obfuscation # 动态 import 会失效,慎用
-enable-export-obfuscation # 仅对 HSP/HAR 生效
-compact # 删多余空格与换行
-remove-log # 移除 console 日志,release 必开
-keep-property-name # 该行之后每行一个要保留的属性名
userName
accessToken
-print-namecache ./nameCache.json # 产出符号映射,必须归档混淆的取舍讲明白一点:-enable-property-obfuscation 收益最大,但只要有一处通过字符串访问属性(obj['fieldName']、JSON 反序列化、动态注册)就会静默失败。开启顺序是先只开 -compact 与 -remove-log 上线一次,确认无异常后再逐条加。 一次全开,问题会堆在一起,二分定位的成本高得多。
-enable-filename-obfuscation 尤其危险:任何按路径动态加载模块的代码(插件化、按需 import)都会失效。没有明确收益就别开。
这张时序图强调两个"不能混"的边界:签名口令只能通过环境变量进 CI,符号表只能留在内部。把 nameCache.json 打进安装包,等于把混淆的意义抹掉一半;把口令写进 build-profile.json5,等于把签名密钥公开。
三条几乎人人都撞过的误解
很多人以为改完 build-profile.json5 的 modules 就能构建新模块,实际上还要磁盘目录和 oh-package.json5 的 name 都对上。少一样就是构建不到。
以为 .hap 装不上的原因是签名算法写错,实际上九成是 profile(.p7b)与 certpath(.cer)不是同一套。或者设备不在该 profile 的调试设备列表里。
以为 HSP 是"全局单例",实际上它只在同进程内共享。跨进程各有一份,依赖全局状态的设计必须显式管理。
两道要动手的题
一,你们工程里有个 1.8MB 的工具库 HAR,被 entry 和 feature 两个 HAP 引用。安装包会增大多少?如果改成 HSP,代价分别是什么?先算再答。
二,把混淆规则里的 -compact 和 -remove-log 单独开一次,跑一遍 release,记录包体积变化。再叠加 -enable-property-obfuscation,看有没有功能坏掉。这两次数据比任何文档都能说服你自己。
几个名词,一次说清
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 任务图 | task graph | 构建任务按依赖关系排成的有向无环图 |
| wrapper | wrapper | 按配置准备并调用正确版本构建器的外壳脚本 |
| 增量构建 | incremental build | 只重跑受影响的任务,靠产物与输入的比对 |
| 动态共享包 | HSP | 独立打包、运行时加载、同进程多 HAP 共享的产物 |
| 静态共享包 | HAR | 被复制进每个引用方的代码包,可含逻辑不可含 UIAbility |
| 符号表 | name cache | 混淆前后名称的映射,用于还原线上崩溃栈 |
| 传递依赖 | transitive dependency | 你的依赖所依赖的库,用 overrides 统一版本 |
| 守护进程 | daemon | 常驻的构建进程,复用它可以省掉重复启动开销 |