hdw2

v2.3.8

Published

7 days ago

鸿蒙 hdc 调试工具

0High
0Medium
0Low

tankunpeng

鸿蒙 next HarmonyOS webview debug hdc hdw hdw2

HDW - HarmonyOS HDC 开发调试工具

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

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

🌟 特色功能

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

📦 安装

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

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

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

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

✅ 验证安装

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

# 检查版本
hdw --version

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

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

🚀 快速开始

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

# 查看所有可用命令
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/

🛠️ 功能详解

设备管理

# 列出连接的所有设备
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 同时安装到真机设备中。

# 安装单个 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 提供了便捷的文件传输功能，支持推送文件到设备、从设备拉取文件、列出设备文件和删除设备文件。

# 推送文件到设备指定目录
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 调试

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

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

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

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

配置管理

# 设置配置项
hdw config set key value

# 获取配置项值
hdw config get key

# 列出所有配置项
hdw config list

# 删除配置项
hdw config del key

直接使用 HDC

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

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

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

系统设置

# 设置 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

📚 相关资源

📝 版本历史

v2.3.1

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

v2.0

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