hvigor 构建体系入门

鸿蒙应用工程的官方构建体系是 hvigor，桌面移植工程的 ArkTS 壳与打包都经它的手。这篇给原生开发背景的同学一个 hvigor 入门：它管什么、不管什么、移植工程怎么与它相处。

▍hvigor 管什么
三件事：ArkTS 与资源的编译；模块依赖与签名配置；HAP 打包。配置核心是工程根的构建配置文件与模块级配置（模块结构、依赖、签名、产物选项）。命令行一次构建即可出包，配合设备工具完成部署安装。

▍移植工程的关键配置
一，预编译库目录：native 库统一放模块的预编译库目录（按 ABI 分目录），hvigor 打包时整体收入——这是上百个 so 的分发通道，hvigor 的闭包机制不适合它们。二，关闭库裁剪选项：hvigor 对 native 库的符号裁剪会把预编译库的段对齐破坏成非法 ELF，设备加载即崩且无日志，这个选项必须关。三，签名配置：调试证书与发布证书分置，发布走云签名流程。四，ABI 过滤：只保留 arm64，包体积立省。

▍hvigor 不管什么
你的 C 与 CPlusPlus 世界它不深管：交叉编译、依赖拼接、补丁应用都在工程自己的脚本体系里（meson、CMake 等），hvigor 只消费它们的产物。理解这个分层很重要：构建世界有两条线，native 线产出 so，hvigor 线产壳与包，两条线在预编译库目录汇合。

▍常见错误
一，把预编译 so 加进 hvigor 依赖闭包指望它链上：闭包只管 ArkTS 与少量 native 模块，预编译库要运行时动态加载。二，改了 native 库没重打包：HAP 里还是旧库，装机行为不变——改库必须重新打包并核对包内字节。三，构建缓存陈旧：产物不一致时清理模块构建目录重来。四，配置文件的注释与格式：这系列配置是 JSON 风格带注释，语法错误会静默跳过整段配置，改完看构建日志确认生效。

▍建议
构建命令写成脚本（构建、打包、部署、启动一条龙）， hvigor 之外的部分也纳入同一入口，团队所有人一条命令出货。

更多真实移植案例，欢迎到 apps 板块翻看 56 篇《鸿蒙PC适配全记录》系列实录。