开源鸿蒙终端工具Termony HAP 包部署和安装指导手册Mac版

❓ 什么是 hdc？

hdc（OpenHarmony Device Connector）是 OpenHarmony 的设备连接工具，类似于 Android 的 adb。它用于：

连接和管理 OpenHarmony 设备/模拟器
推送文件到设备
安装和卸载应用
执行设备上的命令
查看日志和调试信息

📲 部署 HAP 包到设备

✅ 前置条件

在部署 HAP 包之前，请确保：

✅ HAP 包已构建（./build-macos.sh 已执行）
✅ OpenHarmony 设备或模拟器已连接
✅ hdc 工具可用（DevEco Studio 已安装）
✅ 设备连接正常

🛠️ 部署步骤

步骤 1：检查设备连接

bash 复制代码

# 设置 hdc 工具路径
export PATH=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH

# 列出已连接的设备
hdc list targets

# 应该看到设备列表，例如：
# 127.0.0.1:5555

步骤 2：检查 HAP 包

确保 HAP 包已构建：

bash 复制代码

# 检查 HAP 包是否存在
ls -lh entry/build/default/outputs/default/entry-default-unsigned.hap

# 或者检查签名后的 HAP 包
ls -lh entry/build/default/outputs/default/entry-default-signed.hap

步骤 3：执行部署脚本

bash 复制代码

# 使用签名后的 HAP 包（推荐）
./push.sh ./entry/build/default/outputs/default/entry-default-signed.hap

# 或者使用未签名的 HAP 包（仅用于测试）
./push.sh ./entry/build/default/outputs/default/entry-default-unsigned.hap

步骤4：输入验证命令进行验证。

sh 复制代码

gettext --version

🔍 部署过程详解

执行 ./push.sh 后，脚本会执行以下步骤：

1. 环境准备

bash 复制代码

# 设置工具目录路径
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents

# 添加 hdc 工具到 PATH
export PATH=$TOOL_HOME/sdk/default/openharmony/toolchains:$PATH

2. 推送 HAP 包到设备

bash 复制代码

# 将 HAP 包发送到设备的临时目录
hdc file send <HAP包路径> /data/local/tmp

# 输出示例：
# FileTransfer finish, Size:4800298, File count = 1, time:21ms rate:228585.62kB/s

3. 安装 HAP 包

bash 复制代码

# 在设备上安装 HAP 包
hdc shell bm install -p /data/local/tmp/<HAP包文件名>

# 输出示例：
# install bundle successfully.

4. 启动应用

bash 复制代码

# 启动应用的 EntryAbility
hdc shell aa start -a EntryAbility -b <包名>

# 输出示例：
# start ability successfully.

📤 部署输出

成功标志：

部署成功后，你会看到：

文件推送成功：

复制代码

FileTransfer finish, Size:4800298, File count = 1, time:21ms rate:228585.62kB/s

安装成功：
复制代码
```
install bundle successfully.
```
启动成功：
复制代码
```
start ability successfully.
```

应用进程运行：

bash 复制代码

hdc shell "ps -A | grep termony"
# 输出：
#   6433 ?        00:00:00 je.jia.termony
#   6591 136:0    00:00:00 je.jia.termony

⏱️ 部署时间

文件推送：几毫秒到几秒（取决于文件大小和网络速度）
安装应用：1-5 秒（取决于设备性能）
启动应用：1-3 秒（取决于应用大小）

🧯 常见问题

问题 1：找不到 hdc 命令

错误信息：

复制代码

command not found: hdc

解决方案：

bash 复制代码

# 设置 hdc 工具路径
export PATH=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH

# 验证 hdc 可用
hdc list targets

问题 2：设备未连接

错误信息：

复制代码

hdc: error: no devices/emulators found

解决方案：

检查设备连接：
bash 复制代码
```
hdc list targets
```
连接设备：
- 确保 OpenHarmony 设备已通过 USB 连接
- 或者确保模拟器已启动

检查设备状态：

bash 复制代码

hdc shell "getprop ro.build.version.sdk"

问题 3：安装失败

错误信息：

复制代码

install failed: ...

可能原因和解决方案：

签名问题：
- 未签名的 HAP 包可能无法安装到真实设备
- 解决方案：配置签名并重新构建
包名冲突：
- 设备上已安装同名应用
- 解决方案：先卸载旧版本
bash 复制代码
```
hdc shell bm uninstall -n je.jia.termony
```
权限不足：
- 设备未开启开发者模式
- 解决方案：在设备设置中开启开发者模式和 USB 调试

问题 4：启动失败

错误信息：

复制代码

start ability failed: ...

解决方案：

检查应用是否已安装：
bash 复制代码
```
hdc shell bm dump -n je.jia.termony
```
查看应用日志：
bash 复制代码
```
hdc hilog | grep termony
```

重新安装：

bash 复制代码

hdc shell bm uninstall -n je.jia.termony
./push.sh ./entry/build/default/outputs/default/entry-default-unsigned.hap

🧪 验证部署结果

方法 1：检查应用进程

bash 复制代码

# 检查应用是否在运行
hdc shell "ps -A | grep termony"

# 应该看到应用进程

方法 2：查看应用信息

bash 复制代码

# 查看应用详细信息
hdc shell bm dump -n je.jia.termony

方法 3：查看应用日志

bash 复制代码

# 查看应用日志
hdc hilog | grep termony

# 或者查看所有日志
hdc hilog

方法 4：在设备上验证

在设备上打开应用列表
找到 "Termony" 应用
点击启动应用
验证终端功能是否正常

⌨️ 常用 hdc 命令

设备管理：

bash 复制代码

hdc list targets                    # 列出所有设备
hdc tconn <设备ID>                  # 连接到指定设备
hdc kill                            # 断开连接

文件操作：

bash 复制代码

hdc file send <本地文件> <设备路径>  # 推送文件到设备
hdc file recv <设备路径> <本地路径>  # 从设备拉取文件

应用管理：

bash 复制代码

hdc shell bm install -p <HAP路径>   # 安装应用
hdc shell bm uninstall -n <包名>     # 卸载应用
hdc shell bm dump -n <包名>          # 查看应用信息

应用启动：

bash 复制代码

hdc shell aa start -a <Ability> -b <包名>  # 启动应用
hdc shell aa force-stop <包名>              # 停止应用

日志查看：

bash 复制代码

hdc hilog                           # 查看系统日志
hdc hilog | grep <关键词>           # 过滤日志

Shell 命令：

bash 复制代码

hdc shell <命令>                    # 执行设备上的命令
hdc shell "ps -A"                   # 查看进程列表
hdc shell "getprop"                 # 查看系统属性

🧭 完整构建和部署流程总结

从环境配置到应用部署的完整流程：

复制代码

1. 环境配置
   ├── 安装 Homebrew
   ├── 安装开发工具（wget, make, cmake 等）
   └── 配置 GNU 工具优先级

2. HNP 包构建
   ├── 执行 ./create-hnp.sh
   ├── 编译 54 个原生工具和库
   ├── 优化包大小
   ├── 配置 GCC 运行时库
   └── 打包成 base.hnp

3. 应用签名配置（重要！）
   ├── 在 DevEco Studio 中配置签名
   ├── 自动生成签名密钥和配置
   └── 验证签名配置正确

4. HAP 包构建
   ├── 执行 ./build-macos.sh
   ├── 使用 Hvigor 编译 ArkTS 代码
   ├── 使用 CMake/Ninja 编译原生代码
   ├── 打包资源文件
   ├── 添加 HNP 包
   ├── 自动签名 HAP 包（如果已配置签名）
   └── 生成签名后的 HAP 包

5. 部署到设备
   ├── 检查设备连接
   ├── 推送 HAP 包到设备
   ├── 安装应用
   └── 启动应用

📦 总结

完成整个配置、构建和部署流程后，你应该拥有：

开发环境

✅ Homebrew 包管理器
✅ 完整的开发工具链（9 个工具）
✅ GNU 版本的工具（功能更强大）
✅ 统一的开发环境（符合 Linux/GNU 标准）

构建产物

✅ HNP 包（base.hnp）：包含 54 个原生工具和库
✅ HAP 包（entry-default-unsigned.hap）：完整的应用安装包
✅ 签名 HAP 包（可选）：可用于真实设备安装

部署能力

✅ 设备连接工具（hdc）
✅ 应用安装和启动能力
✅ 完整的构建和部署流程

恭喜！你已经完成了 Termony 的完整构建和部署流程！ 🎉