Skip to content

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 只有三行有用,但这一行决定了整个模块能执行什么任务:

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
json5
// 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,按机器内存给
  }
}
json5
// 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 模型已经不推荐了):

json5
// 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 根目录。

bash
#!/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 生成:

text
# 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构建任务按依赖关系排成的有向无环图
wrapperwrapper按配置准备并调用正确版本构建器的外壳脚本
增量构建incremental build只重跑受影响的任务,靠产物与输入的比对
动态共享包HSP独立打包、运行时加载、同进程多 HAP 共享的产物
静态共享包HAR被复制进每个引用方的代码包,可含逻辑不可含 UIAbility
符号表name cache混淆前后名称的映射,用于还原线上崩溃栈
传递依赖transitive dependency你的依赖所依赖的库,用 overrides 统一版本
守护进程daemon常驻的构建进程,复用它可以省掉重复启动开销