HarmonyOS鸿蒙Next项目如何在命令行编译打包

在鸿蒙（HarmonyOS）应用开发中，通过命令行进行编译打包是实现自动化构建、持续集成（CI/CD）的关键环节。借助官方提供的命令行工具 hvigorw（Hvigor wrapper），开发者可以脱离 DevEco Studio 图形界面，高效完成各类构建任务。以下将详细介绍命令行编译打包的完整流程、常用命令及进阶技巧。

一、环境准备

在开始前，请确保你的开发或构建服务器已满足以下基础要求：

• Node.js：建议安装 16.x 或 18.x 版本，用于运行构建脚本。
• HarmonyOS SDK：下载并解压至指定目录（如 /opt/harmonyos-sdk），其中包含 hvigor构建工具。
• 环境变量配置：将 Node.js、HarmonyOS SDK 的 toolchains目录添加到系统的 PATH 环境变量中，以便在任意位置执行 hvigorw命令。
• 项目依赖：在工程根目录下执行 npm install或 hvigorw自动安装所需依赖。

二、核心构建命令

hvigorw支持多种构建任务，以下是最常用的命令及其用途：

1. 清理构建产物
   在开始新构建前，建议先清理旧的输出文件：

   hvigorw clean
   

   若项目配置了多个产品（product），可指定具体产品进行清理：

   hvigorw clean -p product=default
   

2. 构建 HAP 包
   HAP（Harmony Ability Package）是应用的主模块包，对应 entry类型的模块。构建命令需指定目标模块和产品：

   hvigorw assembleHap -p product=default -p module=entry
   

   如需同时构建多个模块，可使用逗号分隔：-p module=entry1,entry2。

3. 构建 APP 包
   APP 包（.app文件）是最终的上架或测试包，包含了所有必需的 HAP 及资源。该命令会自动处理签名（若已配置）：

   hvigorw assembleApp -p product=default
   

4. 构建共享包
   对于静态共享包（HAR）和动态共享包（HSP），分别使用以下命令：

   # 构建 HAR 包
   hvigorw assembleHar -p product=default -p module=library[@default](/user/default)
   # 构建 HSP 包
   hvigorw assembleHsp -p product=default -p module=dynamic[@default](/user/default)
   

三、关键参数详解

通过附加参数可以精细化控制构建行为：

• 指定构建模式：使用 -p buildMode=debug或 -p buildMode=release选择调试版或发布版。默认为 debug 模式（构建 HAP/HAR/HSP 时）或 release 模式（构建 APP 时）1。
• 指定产品：当项目在 build-profile.json5中定义了多个产品时，通过 -p product=产品名指定目标产品。
• 指定模块与目标：结合 --mode module参数，可精确编译特定模块的某个目标：-p module=模块名@目标名。
• 启用构建分析：添加 --analyze=normal或 --analyze=advanced可在 DevEco Studio 中查看构建耗时分析报告。
• 日志级别控制：通过 -d（debug）、-i（info）、-w（warn）、-e（error）调整输出日志的详细程度。

四、进阶场景与技巧

1. 一键打包所有产品
   当项目包含多个产品（如 default、tablet、tv）时，可编写 Shell 脚本批量构建：

   hvigorw assembleApp -p product=default; 
   hvigorw assembleApp -p product=tablet; 
   hvigorw assembleApp -p product=tv
   

   也可在 CI 工具（如 Jenkins）中配置并行任务提升效率。

2. 自定义版本号
   若需在构建时动态注入版本号（如加入日期标识），可在工程级的 hvigorfile.ts中通过插件修改 app.json5的 versionName字段。示例代码如下：

   import { appTasks, OhosPluginId, OhosAppContext, AppJson } from '[@ohos](/user/ohos)/hvigor-ohos-plugin';
   import { hvigor, getNode, HvigorNode } from '[@ohos](/user/ohos)/hvigor';
   const node: HvigorNode = getNode(__filename);
   const appContext = node.getContext(OhosPluginId.OHOS_APP_PLUGIN) as OhosAppContext;
   const appJson5: AppJson.AppOptObj = appContext.getAppJsonOpt();
   if (appContext.getBuildMode() === 'debug') {
     appJson5.app.versionName = '1.0.0-debug-' + new Date().toLocaleDateString();
   } else {
     appJson5.app.versionName = '1.0.0-release-' + new Date().toLocaleDateString();
   }
   appContext.setAppJsonOpt(appJson5);
   

3. 签名与安装
   命令行构建 APP 包时自动使用 build-profile.json5中配置的签名信息。若需安装到设备，可使用 hdc工具：

   hdc install build/outputs/default/entry-default-signed.hap
   

   注意：正式签名包只能通过应用市场分发，调试包仅用于开发测试。

五、注意事项

• 路径限制：除 hvigorw -v、hvigorw --help等查询命令外，其他构建命令均需在工程根目录下执行1。
• 依赖一致性：确保本地或 CI 环境中的 Node.js、HarmonyOS SDK 版本与项目要求一致，避免因版本差异导致构建失败。
• 产物位置：构建生成的 HAP、HAR、HSP 包位于各模块的 build目录下；APP 包位于项目根目录的 build目录中。
• 性能优化：在 ascf.config.json中开启 swc编译、配置缓存等选项可显著提升构建速度。

通过熟练掌握以上命令与参数，你可以轻松将鸿蒙项目的编译打包集成到自动化流水线中，实现代码提交后自动构建、测试和部署，大幅提升团队开发效率。

信息来源

命令行构建工具（hvigorw）-命令行工具 - 华为HarmonyOS开发者