吃透 Hvigor 构建系统、掌握增量编译与缓存机制、学会模块化拆分与并行编译参数调校、把大型工程编译时间缩短 60%~80%

---

一、前置思考：编译等待是"团队效率的隐形税"

1.1 编译时间的真实成本

场景	全量编译	每天次数	每天等待
单模块小型工程	1~2 分钟	20 次	30 分钟
中型工程	5~10 分钟	15 次	1.5 小时
大型工程（50+ 模块）	20~40 分钟	10 次	4~6 小时

核心认知：编译等待打断"开发心流"——等编译的 5 分钟里，开发者的注意力已经
切换到别处。编译提速 = 开发效率 + 开发者幸福感 + CI 吞吐量。

1.2 编译提速的四大维度

维度	手段	典型收益
增量编译	只编译变更模块	-70%~90%
缓存复用	未变更模块直接用缓存	-50%~80%
并行构建	多核并行编译独立模块	-40%~60%
模块化拆分	依赖优化减少级联编译	-30%~50%

关键认知：全量编译优化是"省钱"，增量编译优化是"印钞"——因为 90% 的日常
构建都发生在"只改了一行代码"之后。

1.3 编译提速的 ROI

指标	优化前	优化后
单次全量构建	32 分钟	8 分钟（-75%）
单次增量构建	8 分钟	40 秒（-92%）
日编译总时长	4.2 小时	52 分钟（-79%）
CI 流水线时长	45 分钟	12 分钟（-73%）

---

二、核心原理：Hvigor 构建系统

2.1 Hvigor 是什么

Hvigor 是 HarmonyOS 的构建系统（对标 Gradle），负责：

源码/资源 → 解析依赖 → 编译(ArkTS/Native) → 打包 → 签名 → 产物

hvigor 构建流水线:
configure(配置) → task graph(任务图) → execute(执行) → produce(产出)

2.2 构建阶段拆解

阶段	内容	耗时占比	优化空间
Configure 配置	解析工程/模块配置	5%~10%	精简配置
依赖解析	解析模块依赖关系	5%~10%	模块化优化
ArkTS 编译	源码→字节码	40%~60%	增量/并行/缓存
Native 编译	C++ 编译链接	10%~30%	预编译/缓存
资源处理	资源编译压缩	5%~15%	资源缓存
打包签名	组装 HAP	5%~10%	并行任务

关键认知：ArkTS 编译是最大头，但"大量重复编译"才是真正浪费——
同一模块在没变更时被反复全量编译。

2.3 增量编译机制

增量编译的核心是变更检测：

构建请求
  │
  ▼
计算文件哈希/比对时间戳 → 找出变更模块
  │
  ├─ 变更模块 → 重新编译（只编译这一部分）
  │
  └─ 未变更模块 → 复用上次产物（跳过编译）

增量生效条件：

1. 工程保持模块化（变更隔离在模块内）；
2. 模块公共 API 稳定（变更不穿透依赖）；
3. 构建缓存未失效（配置文件/版本变化会导致失效）。

2.4 缓存失效的常见原因

失效原因	影响	规避
任意配置改动	全量重编	配置集中管理
依赖版本升级	依赖链重编	版本锁定
时间戳漂移	误判变更	哈希检测优于时间戳
缓存目录被清	全部重编	缓存持久化
跨模块 API 变更	下游级联重编	接口契约稳定

---

三、源码/API 深度解析：提速三板斧

3.1 模块化拆分（HAR/HSP）

原理：把大工程拆为多个 HAR（静态库模块）/HSP（共享包），
让变更隔离在单一模块内，增量编译只重编该模块。

❌ 单模块巨兽: 改一行代码 → 全量编译 20 分钟

✅ 模块化: 改 common 模块 → 只重编 common + 依赖它的模块
entry (应用入口)
├── common (基础工具 HAR)
├── ui (UI 组件库 HAR)
├── network (网络层 HAR)
├── data (数据层 HAR)
└── feature_home (业务模块 HAR/HSP)

拆分收益：

场景	全量	模块化+增量
改一行 UI 代码	32 分钟	3 分钟
改 common 工具	32 分钟	8 分钟（含下游）
新增一个页面	32 分钟	5 分钟

3.2 构建缓存策略

// build-profile.json5 缓存配置
{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [],
  // 构建缓存目录: 保持持久化, 不要每次清理
  "buildOption": {
    "arkOptions": {
      "obfuscation": {
        "ruleOptions": { "enable": true, "files": ["./obfuscation-rules.txt"] }
      }
    }
  }
}

缓存纪律：

1. 不要频繁 clean（clean 会清掉全部缓存）；
2. 缓存目录放本地磁盘（SSD 优先），避免网络盘；
3. CI 间共享缓存：增量缓存持久化到 CI 缓存区。

3.3 并行编译参数

Hvigor 支持并行构建与任务并行：

# 命令行并行构建（多模块同时编译）
hvigorw assembleHap --parallel

# 指定并行任务数（默认 = CPU 核数）
hvigorw assembleHap --parallel --parallel-tasks=8

# 构建守护进程（复用编译进程, 避免冷启动开销）
hvigorw assembleHap --daemon

参数	作用	建议
--parallel	模块级并行	默认开启
--parallel-tasks=N	并行任务数	= 物理核数
--daemon	常驻构建进程	建议开启
--no-daemon	一次性进程	内存紧张时
--incremental	增量构建	默认开启

3.4 HSP 预编译

HSP（共享包）可以预编译成产物，主工程直接引用，省去重复编译：

{
  "module": {
    "name": "shared_ui",
    "type": "shared",
    "buildOption": {
      "precompile": true      // 预编译: 产物直接复用
    }
  }
}

预编译适用：稳定且被多模块引用的公共库（UI 组件库、工具库）。

---

四、企业级实战：编译提速完整方案

4.1 编译耗时分析

步骤	动作	工具
① 采集	记录各阶段耗时	hvigorw --info / 构建日志
② 定位	找出最耗时阶段	阶段耗时统计
③ 归因	判断是全量还是缓存失效	缓存命中日志
④ 优化	按四大维度对症	本文方案
⑤ 验证	前后对比	耗时数据

4.2 依赖优化

问题	表现	优化
循环依赖	构建死锁/警告	消除循环
过深依赖链	级联重编	依赖扁平化
多余依赖	变更放大	按需依赖
大依赖	编译慢	拆分为小模块
版本冲突	反复解析	版本统一

依赖优化原则:
1. 高内聚: 相关代码同模块
2. 低耦合: 模块间只暴露稳定接口
3. 依赖倒置: 上层依赖抽象, 不依赖具体实现
4. 稳定依赖: 公共模块尽量少变更

4.3 团队协作优化

实践	收益
模块负责人制	变更可控
接口冻结期	避免高频级联
分支构建策略	按变更模块定向构建
本地+CI 双缓存	加速一切构建

4.4 提速效果评估

指标	优化前	优化后
全量构建	32 分钟	8 分钟
增量构建	8 分钟	40 秒
CI 流水线	45 分钟	12 分钟
周编译总时长	21 小时	4.5 小时

---

五、排查与优化：构建问题定位

5.1 常见构建瓶颈

瓶颈	特征	对策
单模块过大	某模块编译时间占比 50%+	拆分模块
缓存反复失效	每次构建都全量	查配置变更/时间戳
并行度不足	多核利用率低	调 parallel-tasks
Native 编译慢	C++ 阶段占比高	预编译/缓存
IO 瓶颈	等待磁盘	SSD/内存盘
内存不足	构建 OOM/慢	增加内存/减少并行

5.2 高频坑点速查

• 是否频繁执行 clean（清缓存）？
• 是否所有代码堆在一个大模块？
• 模块依赖是否有循环/过深？
• 公共 API 是否频繁变更（级联重编）？
• 并行构建是否开启？
• daemon 进程是否启用？
• 缓存目录是否在 SSD？
• CI 缓存是否持久化？
• Native 库是否可预编译？
• 是否分析过各阶段耗时？

---

六、总结与进阶

6.1 收益模型（参考实测）

指标	优化前	优化后	提升
全量构建	32 分钟	8 分钟	-75%
增量构建	8 分钟	40 秒	-92%
日编译总时长	4.2 小时	52 分钟	-79%
CI 流水线	45 分钟	12 分钟	-73%

6.2 工程规范

1. 模块化评审：新代码归属哪个模块，禁止新增大模块；
2. 接口冻结：公共模块 API 变更需评审；
3. 缓存纪律：不随意 clean，缓存持久化；
4. 构建监控：构建耗时超阈值告警；
5. CI 缓存：CI 与本地共享缓存（第 44 篇联动）。

6.3 进阶方向

• 远程缓存/构建缓存服务：团队共享构建产物；
• 编译期代码生成：减少运行时开销；
• HSP 预编译深度：公共库产物化（第 45 篇模块化联动）；
• 构建可视化：构建耗时看板接入 CI（第 41 篇联动）。

---

附：Demo 演示说明

Tab	演示内容
⚙️ 构建流程	Hvigor 构建 6 阶段时间线 + 耗时占比
🕐 增量编译	全量 vs 增量编译对比（改一行代码场景）
🧩 模块化	模块依赖 DAG 优化前后对比（级联范围）
⚡ 参数调校	并行/缓存/daemon 参数配置卡片 + 收益说明
📊 提速报告	优化前后全量/增量/CI 耗时对比