增量编译与构建缓存加速开发

一、构建速度的重要性

在 11 模块的 HarmonyOS 项目中，一次完整的全量构建可能需要数分钟。如果每次修改代码都需要等待全量构建，开发效率会大打折扣。Hvigor 提供了增量编译和构建缓存两种机制来加速开发。

增量编译和构建缓存的核心思想是：只重新构建发生变化的部分。对于大多数开发场景，每次修改只涉及少量文件，充分利用缓存可以节省 80% 以上的构建时间。

二、.hvigor/cache 缓存机制

Hvigor 的缓存存储在 .hvigor/cache/ 目录下，包含多个缓存文件：

.hvigor/cache/
  ├── file-cache.json     # 文件级缓存记录
  ├── last-build-info.json # 上次构建的信息
  ├── meta.json           # 构建元数据
  ├── project-config.json  # 项目配置快照
  └── task-cache.json     # 任务缓存记录

file-cache.json：记录每个源文件的编译产物哈希值。当文件内容不变时，哈希值不变，构建系统跳过该文件的编译。

last-build-info.json：记录上次构建的配置、时间戳等信息。用于判断是否需要重新构建。

task-cache.json：记录每个构建任务的输入输出。如果任务的所有输入都没有变化，任务可以直接复用上次的结果。

缓存的工作原理：

代码修改 → Hvigor 检查文件哈希
  ├── 哈希未变 → 跳过编译，使用缓存产物
  └── 哈希变化 → 重新编译，更新缓存

三、增量编译的触发条件

增量编译在某些条件下会被触发，而在另一些条件下会退化为全量编译。

触发增量编译的条件：

1. 修改单个源文件：如修改一个 .ets 文件的某行代码，只编译该文件和受影响的文件
2. 修改模块内资源：如修改 resources 目录下的图片或字符串，只重新打包该模块的资源
3. 未修改配置文件：build-profile.json5、oh-package.json5 等配置文件未改变

触发全量编译的条件：

1. 修改 build-profile.json5：项目配置变化，所有缓存失效
2. 修改 hvigorfile.ts：构建脚本变化，所有缓存失效
3. SDK 版本更新：编译器版本变化导致缓存不兼容
4. 执行 clean build：手动删除缓存目录
5. 跨模块接口变化：如果修改了 commonLib 的导出接口，所有引用该模块的代码都需要重新编译

四、clean build 策略

在使用缓存时，某些情况下需要执行 clean build（清理后重建）：

1. 构件残留：老旧缓存可能导致错误的构建结果
2. 依赖更新：第三方库版本更新后，旧缓存可能不兼容
3. 神秘错误：遇到不理解的编译错误时，clean build 可以排除缓存干扰

clean build 的方法：

# 在 DevEco Studio 中
Build → Clean Project
# 或手动删除缓存目录
Remove-Item -Recurse -Force .hvigor/cache/

但在日常开发中，不建议频繁 clean build。缓存的目的是加速开发，频繁清理反而降低效率。建议的节奏是：

• 正常开发：使用增量编译
• 每天一次：Build → Clean Project 保持缓存新鲜
• 遇到奇怪的编译错误：立即 clean build

五、在 11 模块架构中的缓存策略

在多模块架构中，缓存的效率更加显著。假设我们修改了 features/homePage/src/main/ets/viewmodels/HomeVM.ets 文件，那么：

1. homePage 模块：编译该文件以及依赖该文件的组件
2. 其他 features 模块（minePage、topicPage）：不触发重新编译
3. 所有 components 模块（base_select 等）：不触发重新编译
4. commonLib 模块：不触发重新编译
5. entry 模块：如果 entry 引用了 HomeVM，需要重新链接，但不需要重新编译

这就是增量编译的核心优势——只有受影响的部分被重新处理。在 11 模块的架构中，模块化隔离减少了模块间的耦合，也减少了增量编译的影响范围。

六、优化构建缓存命中率的实践

1. 保持接口稳定：公共模块（如 commonLib）的导出接口应保持稳定。接口频繁变化会导致所有依赖模块的缓存失效。

2. 独立模块化：将不常变动的代码（如模型定义、工具函数）放在 commonLib 中，业务代码放在 features 中。这样业务代码的改动不会影响公共模块的缓存。

3. 避免使用通配符导入：import * from 'xxx' 会导致编译器无法精确分析依赖关系，可能触发更多的重新编译。

4. 合理使用 Index.ets：模块的 Index.ets 定义了对外暴露的接口。当 Index.ets 变化时，所有引用该模块的代码会失效。因此 Index.ets 应尽可能稳定。

5. 使用构建报告优化：查看 .hvigor/report/ 目录下的构建报告，分析哪些模块的缓存命中率低，找出原因。

七、构建缓存与版本控制

.hvigor/cache/ 目录不应该提交到 Git 中。在项目根目录的 .gitignore 中已包含：

.hvigor/

这意味着每个开发者 clone 项目后首次构建为全量编译。首次构建较慢是正常现象，后续构建会逐步加速。

对于 CI/CD 流水线，每次构建通常在一个干净的环境中运行（如 Docker 容器），因此无法利用缓存。建议在 CI/CD 中使用以下策略：

• PR 验证构建：关闭缓存（确保每次构建一致）
• 日常集成构建：开启缓存（加速构建速度）
• Release 构建：执行 clean build + 全量构建（确保构建产物干净）

八、总结

增量编译和构建缓存是 Hvigor 加速开发的核心机制。在 11 模块架构中，模块化的设计天然有利于增量编译——修改一个模块不影响其他模块的缓存。理解缓存的触发条件和失效场景，合理使用 clean build 策略，能够在保证构建质量的同时最大化开发效率。核心原则是：正常开发用增量编译，遇到异常用 clean build，构建服务器用全量构建。