hdw2/README.md

鸿蒙 hdc 调试工具

# HDW - HarmonyOS HDC 开发调试工具

HDW 是一款基于 Node.js 的 npm 包，集成了华为 HarmonyOS 的 HDC (HarmonyOS Device Connect) 工具，专为 HarmonyOS Next 应用开发设计。它提供了更友好的命令行接口和额外的实用功能，简化了 HarmonyOS 开发流程中的常见任务。

作为华为 HDC 工具的高级封装，HDW 不仅保留了 HDC 的全部功能，还增加了许多便捷特性，让开发者可以更高效地进行 HarmonyOS 应用开发和调试。

## 🌟 特色功能

1. **内置华为 HDC 工具** - 无需从华为官网单独下载 HDC 命令行工具，自动适配各操作系统平台
2. **Webview 一键调试** - 避免华为官方提供的复杂调试步骤，快速建立远程调试连接
3. **常用功能封装** - 封装 HDC 的常用功能：设备列表、HAP 安装、文件推送/拉取等
4. **端口映射管理** - 提供端口映射列表打印、清除等功能，方便调试多个 WebView 实例
5. **无缝命令映射** - 通过 `hdw hdc ...` 可以使用 HDC 的所有原生命令
6. **全平台支持** - 支持 Windows、macOS (X86/ARM)、Linux 多平台，内置各平台专用工具链
7. **TypeScript 重构** - 使用 TypeScript 完全重写，提供更好的类型安全和开发体验
8. **现代化构建** - 采用 tsup 构建工具，优化代码架构，提高可维护性

## 📦 安装

```bash
# 使用 npm 全局安装
npm install hdw2 -g

# 或使用 yarn 全局安装
yarn global add hdw2

# 或使用 pnpm 全局安装
pnpm install hdw2 -g
```

> **注意**: 最低 Node.js 版本要求为 18+

## ✅ 验证安装

安装完成后，可以通过以下命令验证 HDW 是否正确安装：

```bash
# 检查版本
hdw --version

# 查看所有可用命令
hdw --help
```

如果命令成功执行并返回版本信息或帮助信息，则表示 HDW 已正确安装。

## 🚀 快速开始

安装完成后，您可以直接使用 `hdw` 命令：

```bash
# 查看所有可用命令
hdw --help

# 输出:
Usage: hdw <命令> [选项]
#
Options:
  -v --version                    输出当前版本号
  -h, --help                      显示帮助信息
#
Commands:
  devices [options]               检查当前环境,获取设备列表
  use [options]                   选择默认设备或设置设备备注
  check                           检查当前环境是否可进行webview调试
  list                            查询当前webview调试端口映射列表
  clear                           清空当前webview调试端口映射
  debug [options]                 开始webview调试
  push [options] [extArgs...]     推送文件到设备,默认推送路径为/data/local/tmp/
  pull [options] [extArgs...]     拉取文件到本地,默认拉取路径为/data/local/tmp/
  ls [options] [extArgs...]       获取手机端指定目录文件列表,默认为/data/local/tmp/
  install [options] [extArgs...]  应用安装,传参同hdc install,支持zip、hap格式
  set <key> [values...]           Hdc的常用设置
  get <name>                      获取Hdc的常用数据
  hdc [options] [extArgs...]      执行hdc命令
  rm [options] [extArgs...]       删除设备端指定文件或目录,默认为/data/local/tmp/,输入*删除指定目录下所有文件
  send [options] [extArgs...]     推送小程序、基础库、模板等到设备端应用
  config <action> [values...]     hdw配置设置、获取、删除等操作
  help [命令]                       显示命令帮助信息
#
官方参考文档:
   https://developer.huawei.com/consumer/cn/develop/
```

## 🛠️ 功能详解

### 设备管理

```bash
# 列出连接的所有设备
hdw devices

# 列出所有设备（包括历史设备）
hdw devices -a

# 选择默认设备（交互式选择）
hdw use

# 选择默认设备并显示历史设备
hdw use -a

# 为指定设备设置备注
hdw use -s <deviceId> <nickname>

# 获取设备UDID
hdw get udid

# 移除设备记录
hdw use -r <deviceId>

# 清除默认设备选择
hdw use -c

# 清除所有设备记录
hdw use -C
```

`use` 命令选项说明：
- `-a, --all`: 显示历史设备
- `-s, --set <deviceId nickname>`: 为指定设备设置备注
- `-r, --remove <deviceId>`: 移除指定设备记录
- `-c, --clear`: 清除默认设备选择
- `-C, --clear-all`: 清除所有设备记录

### 应用安装

HDW 2.0 特色功能之一是支持 ZIP 包直接安装。在鸿蒙项目中，当构建产物包含 HSP 和 HAP 文件时，单独安装 HAP 包是无法正常运行的。此时，您可以先将 HSP 文件和 HAP 文件压缩成 ZIP 包，然后使用 `hdw install ./xxxx.zip` 命令，一键将 HSP 和 HAP 同时安装到真机设备中。

```bash
# 安装单个 HAP 包到设备
hdw install path/to/your/app-installer-default-unsigned.hap

# 安装包含 HSP 和 HAP 的 ZIP 包（HDW 2.0 特色功能）
# 注意：当项目构建产物包含 HSP 和 HAP 时，需要将它们打包成 ZIP 文件进行安装
hdw install path/to/your/bundle.zip

# 例如，如果您的项目构建产物包含：
# - module-name.hap
# - module-name.hsp
# 可以将它们压缩成 bundle.zip，然后使用以下命令安装：
hdw install ./bundle.zip
```

这种 ZIP 包安装方式特别适用于 HarmonyOS 的模块化开发场景，能够一次性安装多个组件，确保应用正常运行。

### 文件传输

HDW 提供了便捷的文件传输功能，支持推送文件到设备、从设备拉取文件、列出设备文件和删除设备文件。

```bash
# 推送文件到设备指定目录
hdw push local_file_path /data/local/tmp/remote_directory/

# 推送文件到设备的Download目录（使用-d参数，此时可省略远端路径）
hdw push -d local_file_path

# 推送文件到设备的分享目录（使用-s参数，此时可省略远端路径）
hdw push -s local_file_path

# 从设备Download目录拉取文件文件到当前目录（使用-d参数，此时可省略远端路径）
hdw pull -d remote_file_name

# 从设备分享目录拉取文件到当前目录（使用-s参数，此时可省略远端路径）
hdw pull -s remote_file_name 

# 从设备拉取文件到本地
hdw pull /data/local/tmp/remote_file local_file_path

# 列出设备指定目录内容
hdw ls /data/local/tmp/

# 列出设备Download目录内容（使用-d参数，此时可省略远端路径）
hdw ls -d

# 列出设备分享目录内容（使用-s参数，此时可省略远端路径）
hdw ls -s

# 删除设备上的文件或目录
hdw rm /data/local/tmp/file_or_directory

# 删除设备Download目录下的所有文件（使用-d参数，此时可省略远端路径）
hdw rm * -d

# 删除设备分享目录下的文件（使用-s参数，此时可省略远端路径）
hdw rm -s filename
```

HDW 的文件传输功能支持便捷的 `-d` 和 `-s` 参数：
- `-d` 或 `--download`: 操作设备端的 Download 目录
- `-s` 或 `--share`: 操作设备端的分享目录（华为分享功能相关目录）

参数说明：
- `local_file_path`: 本地文件路径，支持相对路径
- `remote_file_name`: 远端路径，必须是全路径；但在使用 `-d` 或 `-s` 参数时可省略
- 当使用 `-d` 或 `-s` 参数时，会自动定位到相应的预设目录，无需指定完整路径

### WebView 调试

```bash
# 检查当前环境是否支持 WebView 调试
hdw check

# 启动 WebView 调试并建立端口映射
hdw debug

# 列出当前的调试端口映射
hdw list

# 清除当前的调试端口映射
hdw clear
```

### 配置管理

```bash
# 设置配置项
hdw config set key value

# 获取配置项值
hdw config get key

# 列出所有配置项
hdw config list

# 删除配置项
hdw config del key
```

### 直接使用 HDC

如果 HDW 不支持特定的 HDC 功能，可以直接使用原生 HDC 命令：

```bash
# 直接执行 HDC 命令
hdw hdc list targets

# 在设备上执行 shell 命令
hdw hdc shell bm dumpsys bundle
```

### 系统设置

```bash
# 设置 HDC 为 TCP 模式
hdw set tcp 192.168.1.100:12345

# 设置 HDC 为 USB 模式
hdw set usb
```

## 🔧 支持的命令详情

| 命令 | 描述 |
|---|---|
| `devices [options]` | 检查当前环境,获取设备列表，支持 `-a` 选项显示所有设备 |
| `use [options]` | 选择默认设备或设置设备备注，支持 `-a`、`-s`、`-r`、`-c`、`-C` 选项 |
| `check` | 检查当前环境是否可进行 WebView 调试 |
| `list` | 查询当前 WebView 调试端口映射列表 |
| `clear` | 清空当前 WebView 调试端口映射 |
| `debug [options]` | 开始 WebView 调试 |
| `push [options] [extArgs...]` | 推送文件到设备，默认推送路径为 /data/local/tmp/ |
| `pull [options] [extArgs...]` | 拉取文件到本地，默认拉取路径为 /data/local/tmp/ |
| `ls [options] [extArgs...]` | 获取设备指定目录文件列表，默认为 /data/local/tmp/ |
| `install [extArgs...]` | 应用安装，传参同 hdc install，支持 zip、hap 格式 |
| `set <key> [values...]` | HDC 的常用设置 |
| `get <name>` | 获取 HDC 常用数据 |
| `hdc [options] [extArgs...]` | 执行 hdc 命令 |
| `rm [options] [extArgs...]` | 删除设备端指定文件或目录，默认为 /data/local/tmp/，输入 * 删除指定目录下所有文件 |
| `send [options] [extArgs...]` | 推送小程序、基础库、模板等到设备端应用 |
| `config <action> [values...]` | HDW 配置设置、获取、删除等操作 |

## ⚠️ 常见问题与故障排除

### 1. 设备未识别
- 确认鸿蒙手机是否开启了开发者模式
- 确保设备已开启USB调试模式
- 检查USB线缆连接是否正常
- 尝试重新插拔USB线缆

### 2. 端口占用错误
- 如果遇到端口占用错误，请使用 `hdw clear` 清除当前端口映射
- 或使用 `hdw list` 查看当前映射，手动终止不需要的进程

### 3. 安装应用失败
- 确保安装的应用包路径正确
- 检查设备是否有足够的存储空间
- 对于包含HSP和HAP的项目，推荐打包为ZIP格式后安装

### 4. WebView调试无法启动
- 确保设备上运行的应用支持WebView调试
- 检查设备网络连接是否正常
- 使用 `hdw check` 验证环境是否支持WebView调试

## 🛡️ 环境要求

- Node.js 18 或更高版本（HDW 是基于 Node.js 的 npm 包）
- HarmonyOS 开发设备（模拟器或真机）
- 正确的 USB 调试设置（用于物理设备）

## 📄 许可证

MIT License

## 📚 相关资源

- [HarmonyOS 开发者官网](https://developer.huawei.com/consumer/cn/)
- [HDC 工具文档](https://developer.huawei.com/consumer/cn/develop/)

## 📝 版本历史

### v2.3.1
- 新增 `use` 命令，支持选择默认设备和设置设备备注
- 新增设备管理功能，支持显示历史设备
- 优化设备选择交互体验

### v2.0
- 使用 TypeScript 完全重写，提供更好的类型安全和开发体验
- 支持多平台（Windows、macOS X86/ARM、Linux），内置各平台专用工具链
- 采用现代化的构建工具链（tsup）
- 优化代码架构，提高可维护性
- 支持 Node.js 18+
- 更完善的错误处理和日志系统