⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

HarmonyOS应用构建与部署指南：hvigorw、hdc命令详解与自动化流程

harmonyos-build-deploy by fadinglight9291117/arkts_skills

67 周安装量

5 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/fadinglight9291117/arkts_skills --skill harmonyos-build-deploy

开发移动应用工程/构建系统

🇨🇳中文介绍

HarmonyOS 构建与部署

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

第一步：与用户确认操作

重要提示： 在执行任何构建或部署操作之前，请确认用户希望执行的具体操作。请用户从以下选项中选择：

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

为何需要先确认：

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

用户回复后：

仅执行选定的操作
清晰地报告进度和结果

快速参考

# 构建完整应用（增量）
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# 安装到设备（兼容 Git Bash）
# 如果在 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"
# 逐个推送文件到明确的远程文件路径（在 Git Bash 上最可靠）
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# 安装（重新安装）先 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"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

917,400 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

294,600 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

237,000 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

166,500 周安装

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

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

清理构建产物

hvigorw clean --no-daemon

深度清理（针对依赖问题）

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

参数	描述
`-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`	启用构建分析

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

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

# 在设备上创建临时目录（兼容 Git Bash）
# 如果在 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"

# 逐个推送文件到明确的远程文件路径（在 Git Bash 上最可靠）
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# 安装（重新安装）先 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"

命令	描述
`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 版本

命令	描述
`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`	清理应用程序数据

命令	描述
`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、permissions）
`{module}/oh-package.json5`	模块依赖

🇺🇸English

HarmonyOS Build & Deploy

Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.

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:

Operation	Description
Clean build artifacts	Remove previous build cache and outputs
Install dependencies	Use ohpm to install project dependencies
Build project	Use hvigorw to build HAP/APP packages
Install to device	Use hdc to install the app on a device
Full pipeline	Clean → 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

Quick Reference

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

# Install to 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

hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

Note: Build output path is 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.

Clean Build & Deploy

Delegate to subagent with the following steps:

Clean: hvigorw clean --no-daemon
Install dependencies: ohpm install --all
Build: hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
Deploy to device (see Push and Install below)
Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
Report success/failure with details

Deploy Only (No Rebuild)

Delegate to subagent with the following steps:

Read AppScope/app.json5 to get bundleName
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.
Deploy to device (see Push and Install below)
Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
Report success/failure with details

Clean App Cache/Data

Delegate to subagent:

Clean cache: hdc -t <UDID> shell "bm clean -n <bundleName> -c"
Clean data: hdc -t <UDID> shell "bm clean -n <bundleName> -d"
Report success/failure

Build Commands (hvigorw)

Incremental Build (Default)

Use incremental build for normal development - only changed modules are rebuilt:

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

Single Module Build

Build only a specific module for faster iteration:

# 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

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.

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

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

Install Dependencies (ohpm)

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

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

Sync Project

Only needed after modifying build-profile.json5 or oh-package.json5:

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

Build Parameters

Parameter	Description
`-p product={name}`	Target product defined in build-profile.json5
`-p buildMode={debug	release}`
`-p module={name}@{target}`	Target module with `--mode module`
`--mode project`	Build all modules in project
`--mode module`	Build specific module only
`--no-daemon`

Build Outputs

Build output path: outputs/

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

Module Types

Type	Extension	Description
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)

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 Type	Build Command
`"entry"` / `"feature"`	HAP	`assembleHap`
`"shared"`	HSP	`assembleHsp`
`"har"`

Module build outputs: {srcPath}/build/default/outputs/default/

For detailed module discovery, build output structure, and handling unwanted modules, see references/module-discovery.md.

Device Installation (hdc)

hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's adb.

Check Device

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

Push and Install

# 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"

Verify and Launch

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

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

Uninstall

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

hdc Command Reference

Command	Description
`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`

Bundle Manager (bm)

Run via hdc -t <UDID> shell "bm ...":

Command	Description
`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`

Ability Assistant (aa)

Run via hdc -t <UDID> shell "aa ...":

Command	Description
`aa start -a <ability> -b <bundle>`	Start specific ability
`aa force-stop <bundleName>`	Force stop application

Troubleshooting

Error	Cause	Solution
`version code not same`	HSP in output not in build-profile.json5	Remove unwanted HSP files before install (see module-discovery.md)
`install parse profile prop check error`	Signature/profile mismatch	Check 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 compatibleSdkVersion	Update device or lower compatibleSdkVersion
Device not found	Connection issue	Check USB; enable Developer Options (tap build number 7x) and USB debugging; `hdc kill && hdc start`; try different USB port/cable

Key Configuration Files

File	Description
`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

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

Related Skills

arkts-development : ArkTS/ArkUI development patterns, state management, component lifecycle, and API usage. Use alongside this skill when developing HarmonyOS application code.

Weekly Installs

Repository

fadinglight9291…s_skills

GitHub Stars

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPass SocketWarn SnykPass

Installed on

opencode63

codex62

gemini-cli60

github-copilot58

kimi-cli57

cursor57

HarmonyOS应用构建与部署指南：hvigorw、hdc命令详解与自动化流程

🇨🇳中文介绍

HarmonyOS 构建与部署

第一步：与用户确认操作

快速参考

相关 Skills

工作流程

清理构建与部署

仅部署（不重新构建）

清理应用缓存/数据

构建命令 (hvigorw)

增量构建（默认）

单模块构建

清理构建（需要时）

清理构建产物

深度清理（针对依赖问题）

安装依赖 (ohpm)

同步项目

构建参数

构建输出

模块类型

查找模块

设备安装 (hdc)

检查设备

推送和安装

验证和启动

卸载

hdc 命令参考

包管理器 (bm)

Ability 助手 (aa)

故障排除

关键配置文件

参考文件

相关技能