Back to Details

harmonyos-build-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HarmonyOS Build & Deploy

HarmonyOS 构建与部署

Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.
HarmonyOS应用的完整构建、清理、打包及安装工作流。

First Step: Confirm Operation with User

第一步：与用户确认操作

IMPORTANT: Before executing any build or deploy operation, confirm which specific operation(s) the user wants to perform. Ask the user to choose from:
OperationDescription
Clean build artifactsRemove previous build cache and outputs
Install dependenciesUse ohpm to install project dependencies
Build projectUse hvigorw to build HAP/APP packages
Install to deviceUse hdc to install the app on a device
Full pipelineClean → install deps → build → deploy to device
Why confirm first:
  • Different scenarios require different operations (e.g., incremental build vs clean build)
  • Avoid unnecessary time-consuming operations
  • Give user control over the workflow
  • Prevent accidental device installation
After user responds:
  • Execute only the selected operations
  • Report progress and results clearly
重要提示： 在执行任何构建或部署操作前，请确认用户需要执行的具体操作。请让用户从以下选项中选择：
操作描述
清理构建产物删除之前的构建缓存和输出文件
安装依赖使用ohpm安装项目依赖
构建项目使用hvigorw构建HAP/APP安装包
安装到设备使用hdc将应用安装到设备上
完整流水线清理 → 安装依赖 → 构建 → 部署到设备
确认原因：
  • 不同场景需要不同操作（例如增量构建 vs 清理构建）
  • 避免不必要的耗时操作
  • 让用户掌控工作流
  • 防止意外的设备安装
用户回复后：
  • 仅执行用户选择的操作
  • 清晰地报告进度和结果

Quick Reference

快速参考

bash
undefined
bash
undefined

Build complete app (incremental)

构建完整应用（增量构建）

hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

Install to device (Git Bash compatible)

安装到设备（兼容Git Bash）

If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.

如果你在Windows上使用Git Bash，请为hdc命令禁用MSYS路径转换。

export MSYS_NO_PATHCONV=1
INSTALL_DIR="//data/local/tmp/install_$(date +%s)" hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
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)

逐个推送文件到明确的远程文件路径（在Git Bash上最可靠）

for f in outputs/.hap outputs/.hsp; do [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")" done
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

先安装（重新安装）HSP，再安装HAP

for f in outputs/.hsp outputs/.hap; do [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename "$f") -r" done
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

**Note:** Build output path is `outputs/`.
for f in outputs/.hsp outputs/.hap; do [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename "$f") -r" done
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

**注意：** 构建输出路径为 `outputs/`。

Workflows

工作流

IMPORTANT: Build, clean, and deploy operations are long-running (build ~30s, file transfer ~20s). Always delegate these workflows to a subagent to avoid timeout. This also provides better error handling and clearer progress reporting to the user.
重要提示： 构建、清理和部署操作耗时较长（构建约30秒，文件传输约20秒）。请始终将这些工作流委托给子Agent，以避免超时。这也能提供更好的错误处理，并向用户清晰地报告进度。

Clean Build & Deploy

清理构建与部署

Delegate to subagent with the following steps:
  1. Clean: 
    hvigorw clean --no-daemon
  2. Install dependencies: 
    ohpm install --all
  3. Build: 
    hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
  4. Deploy to device (see Push and Install below)
  5. Launch: 
    hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
  6. Report success/failure with details
委托给子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. 详细报告成功/失败结果

Deploy Only (No Rebuild)

仅部署（不重新构建）

Delegate to subagent with the following steps:
  1. Read 
    AppScope/app.json5
    to get bundleName
  2. Check 
    outputs/
    for existing build outputs. If empty or missing, collect signed HAP/HSP from each module's build directory (
    {srcPath}/build/default/outputs/default/*-signed.*
    ) into 
    outputs/
    . See module-discovery.md for details.
  3. Deploy to device (see Push and Install below)
  4. Launch: 
    hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
  5. Report success/failure with details
委托给子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. 详细报告成功/失败结果

Clean App Cache/Data

清理应用缓存/数据

Delegate to subagent:
  1. Clean cache: 
    hdc -t <UDID> shell "bm clean -n <bundleName> -c"
  2. Clean data: 
    hdc -t <UDID> shell "bm clean -n <bundleName> -d"
  3. Report success/failure
委托给子Agent执行：
  1. 清理缓存：
    hdc -t <UDID> shell "bm clean -n <bundleName> -c"
  2. 清理数据：
    hdc -t <UDID> shell "bm clean -n <bundleName> -d"
  3. 报告成功/失败结果

Build Commands (hvigorw)

构建命令（hvigorw）

Incremental Build (Default)

增量构建（默认）

Use incremental build for normal development - only changed modules are rebuilt:
bash
undefined
在日常开发中使用增量构建 - 仅重新构建修改过的模块：
bash
undefined

Build complete app (incremental)

构建完整应用（增量构建）

hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
undefined
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
undefined

Single Module Build

单模块构建

Build only a specific module for faster iteration:
bash
undefined
仅构建特定模块以加快迭代速度：
bash
undefined

Build single HAP module

构建单个HAP模块

hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon

Build single HSP module

构建单个HSP模块

hvigorw assembleHsp -p module=my_feature@default --mode module -p buildMode=release --no-daemon
hvigorw assembleHsp -p module=my_feature@default --mode module -p buildMode=release --no-daemon

Build single HAR module

构建单个HAR模块

hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon
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

**Module name format:** `{moduleName}@{targetName}`
- `moduleName`: Directory name of the module (e.g., `entry`, `my_feature`)
- `targetName`: Target defined in module's `build-profile.json5` (usually `default`)

**When to use single module build:**
- Developing/debugging a specific module
- Faster build times during iteration
- Testing changes in isolated module

**Note:** After single module build, you still need to run `assembleApp` to package the complete application for installation.
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`来打包完整的可安装应用。

Clean Build (When Needed)

清理构建（必要时使用）

Only perform clean build when:
  • First time building the project
  • Encountering unexplained build errors
  • After modifying 
    build-profile.json5
    or SDK version
  • Dependency resolution issues
bash
undefined
仅在以下场景执行清理构建：
  • 首次构建项目
  • 遇到无法解释的构建错误
  • 修改
    build-profile.json5
    或SDK版本后
  • 依赖解析出现问题
bash
undefined

Clean build artifacts

清理构建产物

hvigorw clean --no-daemon
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
undefined
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
undefined

Install Dependencies (ohpm)

安装依赖（ohpm）

bash
undefined
bash
undefined

Install all dependencies (after clean or first clone)

安装所有依赖（清理后或首次克隆项目时）

ohpm install --all
ohpm install --all

With custom registry

使用自定义镜像源

ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"
undefined
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"
undefined

Sync Project

同步项目

Only needed after modifying 
build-profile.json5
or 
oh-package.json5
:
bash
hvigorw --sync -p product=default -p buildMode=release --no-daemon
仅在修改
build-profile.json5
或
oh-package.json5
后需要执行：
bash
hvigorw --sync -p product=default -p buildMode=release --no-daemon

Build Parameters

构建参数

ParameterDescription
-p product={name}
Target product defined in build-profile.json5
-p buildMode={debug|release}
Build mode
-p module={name}@{target}
Target module with 
--mode module
--mode project
Build all modules in project
--mode module
Build specific module only
--no-daemon
Disable daemon (recommended for CI)
--analyze=advanced
Enable build analysis
参数描述
-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
启用构建分析

Build Outputs

构建输出

Build output path: 
outputs/
outputs/
├── entry-default-signed.hap
└── *.hsp
构建输出路径：
outputs/
outputs/
├── entry-default-signed.hap
└── *.hsp

Module Types

模块类型

TypeExtensionDescription
HAP
.hap
Harmony Ability Package - Application entry module
HSP
.hsp
Harmony Shared Package - Dynamic shared library
HAR
.har
Harmony Archive - Static library (compiled into HAP)
APP
.app
Complete application bundle (all HAP + HSP)
类型扩展名描述
HAP
.hap
Harmony Ability Package - 应用入口模块
HSP
.hsp
Harmony Shared Package - 动态共享库
HAR
.har
Harmony Archive - 静态库（编译到HAP中）
APP
.app
完整应用包（包含所有HAP + HSP）

Finding Modules

查找模块

Modules are defined in 
build-profile.json5
at the project root. The module type is determined by the 
type
field in 
{module}/src/main/module.json5
:
type
value		Module TypeBuild Command
"entry"
/ 
"feature"
HAP
assembleHap
"shared"
HSP
assembleHsp
"har"
HAR
assembleHar
Module build outputs: 
{srcPath}/build/default/outputs/default/
For detailed module discovery, build output structure, and handling unwanted modules, see references/module-discovery.md.
模块在项目根目录的
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。

Device Installation (hdc)

设备安装（hdc）

hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's adb.
hdc（HarmonyOS Device Connector）是用于设备通信的CLI工具，类似Android的adb。

Check Device

检查设备

bash
hdc list targets              # List connected devices (returns UDID)
hdc -t <UDID> shell "whoami"  # Test connection
bash
hdc list targets              # 列出已连接设备（返回UDID）
hdc -t <UDID> shell "whoami"  # 测试连接

Push and Install

推送与安装

bash
undefined
bash
undefined

Create temp directory on device (Git Bash compatible)

在设备上创建临时目录（兼容Git Bash）

If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.

如果你在Windows上使用Git Bash，请为hdc命令禁用MSYS路径转换。

export MSYS_NO_PATHCONV=1
INSTALL_DIR="//data/local/tmp/install_$(date +%s)" hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
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)

逐个推送文件到明确的远程文件路径（在Git Bash上最可靠）

for f in outputs/.hap outputs/.hsp; do [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")" done
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

先安装（重新安装）HSP，再安装HAP

for f in outputs/.hsp outputs/.hap; do [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename "$f") -r" done
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"
undefined
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
undefined

Verify and Launch

验证与启动

bash
undefined
bash
undefined

Check installation

检查安装状态

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

Launch app (default ability)

启动应用（默认Ability）

hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
undefined
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
undefined

Uninstall

卸载

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

hdc Command Reference

hdc命令参考

CommandDescription
hdc list targets
List connected devices
hdc -t <UDID> shell "<cmd>"
Execute shell command on device
hdc -t <UDID> file send <local> <remote>
Push file/directory to device
hdc -t <UDID> file recv <remote> <local>
Pull file/directory from device
hdc kill
Kill hdc server
hdc start
Start hdc server
hdc version
Show hdc version
命令描述
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)

包管理器（bm）

Run via 
hdc -t <UDID> shell "bm ..."
:
CommandDescription
bm install -p <path>
Install from directory (all HAP/HSP)
bm install -p <file.hap>
Install single HAP file
bm install -r -p <path>
Reinstall (replace existing, keep data)
bm uninstall -n <bundleName>
Uninstall application
bm dump -n <bundleName>
Show package info
bm dump -a
List all installed packages
bm clean -n <bundleName> -c
Clean application cache
bm clean -n <bundleName> -d
Clean application data
通过
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)

Ability助手（aa）

Run via 
hdc -t <UDID> shell "aa ..."
:
CommandDescription
aa start -a <ability> -b <bundle>
Start specific ability
aa force-stop <bundleName>
Force stop application
通过
hdc -t <UDID> shell "aa ..."
执行：
命令描述
aa start -a <ability> -b <bundle>
启动指定Ability
aa force-stop <bundleName>
强制停止应用

Troubleshooting

故障排查

ErrorCauseSolution
version code not same
HSP in output not in build-profile.json5Remove unwanted HSP files before install (see module-discovery.md)
install parse profile prop check error
Signature/profile mismatchCheck signing config in build-profile.json5; verify bundleName matches app.json5; check certificate not expired
install failed due to older sdk version
Device SDK < app's compatibleSdkVersionUpdate device or lower compatibleSdkVersion
Device not foundConnection issueCheck USB; enable Developer Options (tap build number 7x) and USB debugging; 
hdc kill && hdc start
; try different USB port/cable
signature verification failed
Invalid or expired certificateRegenerate certificate in DevEco Studio; check validity period; ensure correct signing config for build type
错误原因解决方案
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中重新生成证书；检查证书有效期；确保构建类型使用正确的签名配置

Key Configuration Files

关键配置文件

FileDescription
AppScope/app.json5
App metadata (bundleName, versionCode, versionName)
build-profile.json5
Modules list, products, signing configs
{module}/src/main/module.json5
Module config (abilities, permissions)
{module}/oh-package.json5
Module dependencies
文件描述
AppScope/app.json5
应用元数据（bundleName、versionCode、versionName）
build-profile.json5
模块列表、产品配置、签名配置
{module}/src/main/module.json5
模块配置（Ability、权限）
{module}/oh-package.json5
模块依赖

Reference Files

参考文档

  • Module Discovery & Build Outputs: references/module-discovery.md - Module definitions, type identification, build output paths, unwanted modules
  • Complete Installation Guide: references/device-installation.md - Version verification scripts and installation script
  • 模块发现与构建输出：references/module-discovery.md - 模块定义、类型识别、构建输出路径、无用模块处理
  • 完整安装指南：references/device-installation.md - 版本验证脚本和安装脚本

Related Skills

相关技能

  • arkts-development: ArkTS/ArkUI development patterns, state management, component lifecycle, and API usage. Use alongside this skill when developing HarmonyOS application code.
  • arkts-development：ArkTS/ArkUI开发模式、状态管理、组件生命周期及API使用。开发HarmonyOS应用代码时可搭配本技能使用。