harmonyos-build-deploy

HarmonyOS 构建与部署

构建、清理、打包和安装 HarmonyOS 应用的完整工作流。

第一步：向用户确认操作

重要： 执行任何构建或部署操作之前，请先确认用户要执行哪些具体操作。请用户从以下选项中选择：

操作	说明
清理构建产物	移除之前的构建缓存和输出
安装依赖	使用 ohpm 安装项目依赖
构建项目	使用 hvigorw 构建 HAP/APP 包
安装到设备	使用 hdc 将应用安装到设备
完整流程	清理 → 安装依赖 → 构建 → 部署到设备

先确认的原因：

• 不同场景需要不同操作（例如增量构建与清理构建）
• 避免执行不必要且耗时的操作
• 让用户掌控工作流
• 防止意外安装到设备

用户回复后：

• 仅执行用户选择的操作
• 清晰报告进度和结果

快速参考

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# List connected devices (returns UDID)
hdc list targets

注意： 构建输出路径为 outputs/。有关设备安装，请参阅推送和安装。

工作流

重要： 构建、清理和部署操作运行时间较长（构建约 30 秒，文件传输约 20 秒）。请始终将这些工作流交给子 Agent执行，以避免超时。这样还能更好地处理错误，并向用户清晰报告进度。

清理、构建并部署

将以下步骤交给子 Agent 执行：

1. 清理：hvigorw clean --no-daemon
2. 安装依赖：ohpm install --all
3. 构建：hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
4. 部署到设备（见下文推送和安装）
5. 启动：hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
6. 详细报告成功或失败

仅部署（不重新构建）

将以下步骤交给子 Agent 执行：

1. 读取 AppScope/app.json5，获取 bundleName
2. 检查 outputs/ 中是否存在构建输出。如果为空或不存在，则从各模块的构建目录（{srcPath}/build/default/outputs/default/*-signed.*）收集已签名的 HAP/HSP 到 outputs/。详情见 module-discovery.md。
3. 部署到设备（见推送和安装）
4. 启动：hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
5. 详细报告成功或失败

清理应用缓存/数据

将以下步骤交给子 Agent 执行：

1. 清理缓存：hdc -t <UDID> shell "bm clean -n <bundleName> -c"
2. 清理数据：hdc -t <UDID> shell "bm clean -n <bundleName> -d"
3. 报告成功或失败

构建命令（hvigorw）

增量构建（默认）

日常开发使用增量构建，仅重新构建已更改的模块：

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

构建单个模块

仅构建指定模块，以加快迭代速度：

# Build single HAP module
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon

# Build single HSP module
hvigorw assembleHsp -p module=my_feature@default --mode module -p buildMode=release --no-daemon

# Build single HAR module
hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon

# Build multiple modules at once
hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p buildMode=release --no-daemon

模块名称格式： {moduleName}@{targetName}

• moduleName：模块目录名称（例如 entry、my_feature）
• targetName：模块 build-profile.json5 中定义的目标（通常为 default）

适合使用单模块构建的情况：

• 开发或调试特定模块
• 迭代期间加快构建速度
• 在隔离的模块中测试更改

注意： 单模块构建后，仍需运行 assembleApp，将完整应用打包以便安装。

清理构建（必要时使用）

仅在以下情况下执行清理构建：

• 首次构建项目
• 遇到无法解释的构建错误
• 修改 build-profile.json5 或 SDK 版本后
• 依赖解析问题

# Clean build artifacts
hvigorw clean --no-daemon

# Deep clean (for dependency issues)
ohpm clean && ohpm cache clean
ohpm install --all
hvigorw --sync -p product=default -p buildMode=release --no-daemon
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

安装依赖（ohpm）

# Install all dependencies (after clean or first clone)
ohpm install --all

# With custom registry
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"

同步项目

仅在修改 build-profile.json5 或 oh-package.json5 后需要执行：

hvigorw --sync -p product=default -p buildMode=release --no-daemon

构建参数

参数	描述
-p product={name}	指定 build-profile.json5 中定义的目标产品
-p buildMode={debug|release}	构建模式
-p module={name}@{target}	配合 --mode module 指定目标模块
--mode project	构建项目中的所有模块
--mode module	仅构建指定模块
--no-daemon	禁用守护进程（推荐用于 CI）
--analyze=advanced	启用构建分析

构建输出

构建输出路径：outputs/

outputs/
├── entry-default-signed.hap
└── *.hsp

模块类型

类型	扩展名	描述
HAP	.hap	Harmony Ability Package - 应用入口模块
HSP	.hsp	Harmony Shared Package - 动态共享库
HAR	.har	Harmony Archive - 静态库（编译到 HAP 中）
APP	.app	完整应用包（包含所有 HAP + HSP）

查找模块

模块定义在项目根目录的 build-profile.json5 中。模块类型由 {module}/src/main/module.json5 中的 type 字段决定：

type 值	模块类型	构建命令
"entry" / "feature"	HAP	assembleHap
"shared"	HSP	assembleHsp
"har"	HAR	assembleHar

模块构建输出：{srcPath}/build/default/outputs/default/

有关模块发现、构建输出结构和处理不需要的模块的详细信息，请参阅 references/module-discovery.md。

设备安装（hdc）

hdc（HarmonyOS Device Connector）是用于设备通信的命令行工具，类似于 Android 的 adb。

检查设备

hdc list targets              # List connected devices (returns UDID)
hdc -t <UDID> shell "whoami"  # Test connection

推送并安装

# Create temp directory on device (Git Bash compatible)
# If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.
export MSYS_NO_PATHCONV=1

INSTALL_DIR="//data/local/tmp/install_$(date +%s)"
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"

# Push files one-by-one to explicit remote file paths (most reliable on Git Bash)
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# Install (reinstall) HSPs first, then the HAP
for f in outputs/*.hsp outputs/*.hap; do
    [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename \"$f\") -r"
done

# Clean up temp directory
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

验证并启动

# Check installation
hdc -t <UDID> shell "bm dump -n <bundleName>"

# Launch app (default ability)
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"

卸载

hdc -t <UDID> shell "bm uninstall -n <bundleName>"

hdc 命令参考

命令	描述
hdc list targets	列出已连接的设备
hdc -t <UDID> shell "<cmd>"	在设备上执行 shell 命令
hdc -t <UDID> file send <local> <remote>	将文件/目录推送到设备
hdc -t <UDID> file recv <remote> <local>	从设备拉取文件/目录
hdc kill	终止 hdc 服务
hdc start	启动 hdc 服务
hdc version	显示 hdc 版本

Bundle Manager（bm）

通过 hdc -t <UDID> shell "bm ..." 运行：

命令	描述
bm install -p <path>	从目录安装（所有 HAP/HSP）
bm install -p <file.hap>	安装单个 HAP 文件
bm install -r -p <path>	重新安装（替换现有版本并保留数据）
bm uninstall -n <bundleName>	卸载应用
bm dump -n <bundleName>	显示软件包信息
bm dump -a	列出所有已安装的软件包
bm clean -n <bundleName> -c	清除应用缓存
bm clean -n <bundleName> -d	清除应用数据

Ability Assistant（aa）

通过 hdc -t <UDID> shell "aa ..." 运行：

命令	描述
aa start -a <ability> -b <bundle>	启动指定的 Ability
aa force-stop <bundleName>	强制停止应用

故障排除

错误	原因	解决方案
version code not same	输出中的 HSP 未包含在 build-profile.json5 中	安装前移除不需要的 HSP 文件（参见 module-discovery.md）
install parse profile prop check error	签名/配置文件不匹配	检查 build-profile.json5 中的签名配置；确认 bundleName 与 app.json5 一致；检查证书是否过期
install failed due to older sdk version	设备 SDK 版本低于应用的 compatibleSdkVersion	更新设备或降低 compatibleSdkVersion
未找到设备	连接问题	检查 USB 连接；启用开发者选项（点击版本号 7 次）和 USB 调试；运行 hdc kill && hdc start；尝试更换 USB 端口/线缆
signature verification failed	证书无效或已过期	在 DevEco Studio 中重新生成证书；检查有效期；确保构建类型使用了正确的签名配置

关键配置文件

文件	描述
AppScope/app.json5	应用元数据（bundleName、versionCode、versionName）
build-profile.json5	模块列表、产品、签名配置
{module}/src/main/module.json5	模块配置（abilities、权限）
{module}/oh-package.json5	模块依赖项

参考文件

• 模块发现与构建输出：references/module-discovery.md - 模块定义、类型识别、构建输出路径、不需要的模块
• 完整安装指南：references/device-installation.md - 版本验证脚本和安装脚本

相关技能

• arkts-development：ArkTS/ArkUI 开发模式、状态管理、组件生命周期和 API 用法。开发 HarmonyOS 应用代码时，请与此技能配合使用。