重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
harmonyos-build-deploy by fadinglight9291117/arkts_skills
npx skills add https://github.com/fadinglight9291117/arkts_skills --skill harmonyos-build-deploy完整的 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 开发者,精准高效
注意: 构建输出路径是 outputs/。
重要提示: 构建、清理和部署操作是长时间运行的(构建约 30 秒,文件传输约 20 秒)。始终将这些工作流程委托给 子代理 以避免超时。这也能为用户提供更好的错误处理和更清晰的进度报告。
委托给子代理,步骤如下:
hvigorw clean --no-daemonohpm install --allhvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemonhdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"委托给子代理,步骤如下:
AppScope/app.json5 获取 bundleNameoutputs/ 是否存在已有的构建输出。如果为空或缺失,则从每个模块的构建目录({srcPath}/build/default/outputs/default/*-signed.*)收集已签名的 HAP/HSP 到 outputs/。详情请参阅 module-discovery.md。hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"委托给子代理:
hdc -t <UDID> shell "bm clean -n <bundleName> -c"hdc -t <UDID> shell "bm clean -n <bundleName> -d"正常开发时使用增量构建 - 仅重建已更改的模块:
# 构建完整应用(增量)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
仅构建特定模块以加快迭代速度:
# 构建单个 HAP 模块
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon
# 构建单个 HSP 模块
hvigorw assembleHsp -p module=my_feature@default --mode module -p buildMode=release --no-daemon
# 构建单个 HAR 模块
hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon
# 同时构建多个模块
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 版本后
依赖解析问题
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
# 安装所有依赖(清理后或首次克隆后)
ohpm install --all
# 使用自定义仓库
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 (HarmonyOS Device Connector) 是用于设备通信的 CLI 工具,类似于 Android 的 adb。
hdc list targets # 列出连接的设备(返回 UDID)
hdc -t <UDID> shell "whoami" # 测试连接
# 在设备上创建临时目录(兼容 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 -t <UDID> shell "bm dump -n <bundleName>"
# 启动应用(默认 Ability)
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
hdc -t <UDID> shell "bm uninstall -n <bundleName>"
| 命令 | 描述 |
|---|---|
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 版本 |
通过 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 | 清理应用程序数据 |
通过 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、permissions) |
{module}/oh-package.json5 | 模块依赖 |
每周安装数
67
仓库
GitHub 星标数
5
首次出现
2026年2月4日
安全审计
安装于
opencode63
codex62
gemini-cli60
github-copilot58
kimi-cli57
cursor57
Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.
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:
After user responds:
# 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/.
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.
Delegate to subagent with the following steps:
hvigorw clean --no-daemonohpm install --allhvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemonhdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"Delegate to subagent with the following steps:
AppScope/app.json5 to get bundleNameoutputs/ 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.hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"Delegate to subagent:
hdc -t <UDID> shell "bm clean -n <bundleName> -c"hdc -t <UDID> shell "bm clean -n <bundleName> -d"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
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:
Note: After single module build, you still need to run assembleApp to package the complete application for installation.
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
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
# Install all dependencies (after clean or first clone)
ohpm install --all
# With custom registry
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"
Only needed after modifying build-profile.json5 or oh-package.json5:
hvigorw --sync -p product=default -p buildMode=release --no-daemon
| 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 output path: outputs/
outputs/
├── entry-default-signed.hap
└── *.hsp
| 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) |
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.
hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's 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>"
| 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 |
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 |
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 |
| 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 |
| 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 |
Weekly Installs
67
Repository
GitHub Stars
5
First Seen
Feb 4, 2026
Security Audits
Gen Agent Trust HubPassSocketWarnSnykPass
Installed on
opencode63
codex62
gemini-cli60
github-copilot58
kimi-cli57
cursor57
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
122,000 周安装
| Disable daemon (recommended for CI) |
--analyze=advanced | Enable build analysis |
assembleHar |
| Start hdc server |
hdc version | Show hdc version |
| List all installed packages |
bm clean -n <bundleName> -c | Clean application cache |
bm clean -n <bundleName> -d | Clean application data |
signature verification failed | Invalid or expired certificate | Regenerate certificate in DevEco Studio; check validity period; ensure correct signing config for build type |