目录

一、HDC 是什么？

二、使用前的准备工作

（一）环境搭建

（二）设备连接

三、HDC 交互命令详细解析

（一）基础命令

（二）文件操作命令

（三）应用管理命令

（四）系统与设备操作命令

（五）日志与调试命令

四、常见问题与解决方法

五、总结与展望

---

一、HDC 是什么？

HDC，即 HarmonyOS Device Connector，是 HarmonyOS 为开发人员提供的用于调试的命令行工具，通过该工具可以在 Windows、Linux、Mac 系统上与真实设备或者模拟器进行交互。简单来说，它就像是一座桥梁，搭建起了开发环境与鸿蒙设备之间的沟通渠道 ，让开发者能够方便地对设备进行各种调试操作。比如在开发鸿蒙应用时，我们可以通过 HDC 将应用安装到设备上进行测试，查看设备的日志信息来排查问题，或者对设备进行文件传输等操作。

HDC 通过 HarmonyOS SDK 获取，存放于 sdk 的 toolchains 目录下，使用时需要将 sdk 的 toolchains 目录添加到环境变量，这样我们才能在命令行中方便地使用它。就好比我们要使用某个工具，首先得把它放在一个系统能够找到的地方，添加环境变量就是这个作用。

二、使用前的准备工作

（一）环境搭建

在使用 HDC 之前，我们首先要确保开发环境中已经获取了 HDC 工具。前面我们提到它通过 HarmonyOS SDK 获取，存放在 SDK 的 toolchains 目录下 。如果你还没有下载 HarmonyOS SDK ，可以前往华为开发者官方网站，按照官方指引进行下载和安装。安装完成后，你就能在对应的 toolchains 目录中找到 HDC 工具了。

接下来，我们需要将 HDC 工具所在的目录添加到环境变量中，这样在命令行中就可以直接使用 HDC 命令，而无需每次都切换到工具所在的目录。以 Windows 系统为例，具体步骤如下：

1. 右键点击 “此电脑”，选择 “属性”；

1. 在弹出的窗口中，点击左侧的 “高级系统设置”；

1. 在 “系统属性” 窗口的 “高级” 选项卡下，点击 “环境变量” 按钮；

1. 在 “环境变量” 窗口的 “系统变量” 中，找到 “Path” 变量，选中它并点击 “编辑”；

1. 在弹出的 “编辑环境变量” 窗口中，点击 “新建”，然后将 HarmonyOS SDK 中 toolchains 目录的路径粘贴进去，例如 “C:\Program Files\Huawei\HarmonyOS SDK\toolchains” ，不同的安装路径请自行修改；

1. 依次点击 “确定” 关闭所有窗口，完成环境变量的设置。

对于 Linux 和 Mac 系统，添加环境变量的方式有所不同，但原理是一样的。以 Mac 系统为例，假设你的 SDK 安装在 “/Users/yourusername/HarmonyOS/sdk/toolchains” 路径下，可以通过以下步骤添加环境变量：

1. 打开终端；

1. 输入 “vi ~/.bash_profile”（如果你的系统默认使用 zsh，则输入 “vi ~/.zshrc”），然后回车，打开环境变量配置文件；

1. 在文件中添加 “export PATH=$PATH:/Users/yourusername/HarmonyOS/sdk/toolchains” ，保存并退出文件（在 vi 编辑器中，按 “Esc” 键，然后输入 “:wq” 并回车）；

1. 输入 “source ~/.bash_profile”（或 “source ~/.zshrc”），使环境变量生效。

完成环境变量设置后，我们可以在命令行中输入 “hdc -v” ，如果能正确输出版本信息，就说明 HDC 工具已经可以正常使用了。

（二）设备连接

环境搭建完成后，接下来就是连接设备了。这里的设备可以是真实的鸿蒙设备，也可以是模拟器。

如果是真机连接，首先要确保设备开启了 USB 调试功能。不同品牌和型号的鸿蒙设备开启 USB 调试的步骤可能略有不同，但大致思路是相似的。一般来说，我们可以在设备的 “设置” 中找到 “关于手机” 或 “关于设备” 选项，进入后连续点击 “版本号” 多次，直到提示已开启开发者模式。然后返回 “设置”，在 “系统” 或 “系统与更新” 中找到 “开发者选项”，进入后打开 “USB 调试” 开关 。例如华为手机，在 “设置” - “关于手机” - 连续点击 “版本号” 7 次激活开发者选项，再在 “设置” - “系统和更新” - “开发人员选项” 中开启 “USB 调试” 。

开启 USB 调试后，使用 USB 线将设备连接到电脑。连接成功后，设备可能会弹出提示，询问是否允许 USB 调试，选择 “允许” 并勾选 “始终允许从这台计算机进行调试” 。此时，在命令行中输入 “hdc list targets” ，如果能列出设备信息，就说明设备连接成功了。

除了 USB 连接，HDC 还支持 TCP 连接，这种方式在一些特殊场景下非常有用，比如设备不方便使用 USB 线连接时。使用 TCP 连接的前提是设备和电脑在同一局域网内。具体步骤如下：

1. 确保设备开启了 USB 调试，并通过 USB 线连接到电脑；

1. 在命令行中输入 “hdc tmode port [port_number]” ，其中 “[port_number]” 是你要设置的端口号，例如 “hdc tmode port 8710” ，这一步是让设备开启 TCP 连接模式并监听指定端口；

1. 断开 USB 连接；

1. 输入 “hdc tconn [device_ip]:[port_number]” ，其中 “[device_ip]” 是设备的 IP 地址，“[port_number]” 是上一步设置的端口号，例如 “hdc tconn 192.168.1.100:8710” ，如果连接成功，就可以通过 TCP 方式对设备进行调试了。

当有多台设备连接到电脑时，我们需要指定目标设备。在执行 HDC 命令时，可以通过 “-t” 参数加上设备的标识符来指定目标设备。如果是通过 USB 连接，设备标识符为序列号；如果是通过网络连接，标识符为 “IP 地址：端口号” 。例如，要在多设备连接时，在指定设备上安装应用，可以使用命令 “hdc -t [connect-key] install [path_to_apk]” ，将 “[connect-key]” 替换为目标设备的标识符，“[path_to_apk]” 替换为应用的安装包路径。

三、HDC 交互命令详细解析

（一）基础命令

1. 查看帮助信息：在命令行中输入 “hdc -h” 或 “hdc help” ，即可获取 HDC 的帮助信息。这些信息包含了 HDC 所有可用的命令以及它们的简要描述和使用方法，就像一本操作手册，当我们不知道某个命令怎么使用时，它能快速给予指导。例如，当我们想要了解文件传输命令的具体参数时，通过查看帮助信息就能找到答案。

1. 查看版本号：执行 “hdc -v” 或 “hdc version” ，会输出版本信息，比如 “Ver: 2.0.0a” 。了解版本号很重要，一方面，新版本可能会修复旧版本的一些问题或者增加新的功能，通过查看版本号，我们能知道自己使用的 HDC 是否是最新版本，以便及时更新，获取更好的开发体验；另一方面，在遇到问题向技术支持寻求帮助时，版本号也是重要的信息之一，有助于快速定位问题。

1. 查询已连接设备：使用 “hdc list targets” 命令可以列出所有已连接的目标设备。如果想要查看更详细的设备信息，比如设备的连接方式（USB 还是 TCP）、连接状态等，可以加上 “-v” 选项，即 “hdc list targets -v” 。当有多台设备连接时，这个命令能帮助我们清晰地识别每一台设备，为后续针对特定设备的操作提供依据。比如在多设备开发测试场景中，我们可以通过这个命令查看各个设备的状态，然后选择需要进行操作的设备 。

（二）文件操作命令

1. 文件传输

• • 从本地发送文件至设备：命令格式为 “hdc file send local remote” ，其中 “local” 是本地文件的路径，“remote” 是设备上接收文件的路径。例如，我们要将本地 “C:\Users\test\Desktop\test.txt” 文件发送到设备的 “/data/local/tmp/” 目录下，就可以使用命令 “hdc file send C:\Users\test\Desktop\test.txt/data/local/tmp/test.txt” 。执行成功后，会显示文件传输的相关信息，如传输完成的提示、文件大小、传输时间和速率等 。

• • 从设备拉取文件至本地：使用 “hdc file recv [-a] remote local” 命令，“remote” 是设备上文件的路径，“local” 是本地接收文件的路径，“-a” 参数可选，加上它文件会保留时间戳模式。比如从设备的 “/data/local/tmp/a.txt” 文件拉取到本地 “D:\downloads\” 目录下，命令为 “hdc file recv /data/local/tmp/a.txt D:\downloads\a.txt” 。

1. 目录操作：在设备端进行目录相关操作时，列出目录内容可以使用 “hdc shell ls [目录路径]” 命令。如果不指定目录路径，默认列出当前目录的内容。例如，要查看设备 “/system” 目录下的文件和子目录，可以执行 “hdc shell ls /system” ，命令执行后会显示该目录下的所有文件和文件夹列表，方便我们了解设备上目录的结构和内容 。

（三）应用管理命令

1. 安装与卸载

• • 安装应用：命令为 “hdc app install [-rdg] PACKAGE” 。其中 “PACKAGE” 是应用的安装包路径；“-r” 参数表示重新安装应用，即覆盖原来已安装的应用；“-d” 参数用于允许安装降级版本的应用（一般情况下，应用不允许降级安装，使用此参数可突破限制）；“-g” 参数用于授予应用所有的运行时权限 。例如，要安装 “D:\apps\myapp.hap” 应用，并授予所有权限，可以使用命令 “hdc app install -g D:\apps\myapp.hap” 。

• • 卸载应用：使用 “hdc app uninstall [-k] PACKAGE” 命令，“PACKAGE” 是应用的包名。“-k” 参数可选，加上它表示卸载应用时保留应用的数据和缓存，下次重新安装该应用时，数据还能保留。比如卸载包名为 “com.example.myapp” 的应用，命令为 “hdc app uninstall com.example.myapp” 。

1. 应用状态控制：强制停止应用可以使用 “hdc shell am force - stop [appName]” 命令，“appName” 是应用的包名。当应用出现异常无响应，或者我们想要快速结束某个应用的运行时，就可以使用这个命令。例如，要强制停止包名为 “com.example.game” 的游戏应用，可以执行 “hdc shell am force - stop com.example.game” ，应用会立即停止运行 。

（四）系统与设备操作命令

1. 系统分区挂载：以读写模式挂载系统分区的命令是 “hdc target mount” 。在默认情况下，系统分区可能是只读的，某些开发和调试操作可能需要对系统分区进行读写操作，这时就可以使用这个命令。例如，我们想要修改系统分区中的某个配置文件，就需要先挂载系统分区为读写模式 。挂载成功后，就可以对系统分区进行文件的读取、写入和修改等操作了。不过需要注意的是，对系统分区的操作要谨慎，不正确的操作可能会导致系统不稳定甚至无法启动。

1. 设备重启：重启设备有两种常用命令，一是 “hdc target boot” ，二是 “hdc shell reboot” 。这两个命令都能实现设备重启的功能，在开发过程中，当我们对设备进行了一些系统级别的配置更改，或者想要重新初始化设备状态时，就可以使用这两个命令重启设备 。比如我们修改了设备的一些网络配置参数，需要重启设备使配置生效，就可以选择其中一个命令来重启设备。

（五）日志与调试命令

1. 日志查看与保存

• • 查看日志：通过 “hdc hilog” 命令可以查看设备的日志信息。日志中记录了设备系统和应用运行过程中的各种事件和状态信息，对于开发人员排查问题非常重要。比如应用在运行过程中出现了崩溃的情况，我们可以通过查看日志来了解崩溃发生的时间、相关的函数调用栈等信息，从而定位问题所在 。

• • 开始和停止保存日志到文件：开始保存日志到文件使用 “hdc shell hilog -w start” 命令，执行后会在设备上开始记录日志到文件中；停止保存日志则使用 “hdc shell hilog -w stop” 命令。保存的日志文件可以后续进行分析，对于一些难以实时捕捉的问题，通过分析日志文件能更好地找到问题的根源 。

1. 端口转发：本地端口转发到手机的命令是 “hdc fport local remote” ，其中 “local” 是本地主机的端口，“remote” 是设备侧的端口。例如，我们要将本地的 1234 端口转发到设备的 5678 端口，可以使用命令 “hdc fport tcp:1234 tcp:5678” 。端口转发在一些特殊的开发场景中非常有用，比如我们在本地开发一个 Web 应用，需要在设备上进行测试，通过端口转发就可以将设备的请求转发到本地的开发服务器上，实现设备与本地开发环境的通信 。

四、常见问题与解决方法

在使用 HDC 交互命令时，可能会遇到一些问题，以下是常见问题及解决方法：

1. 设备无法识别：执行 “hdc list targets” 命令后，没有列出任何设备。这可能是因为设备驱动未正确安装、USB 线连接不稳定或者设备未开启 USB 调试。解决方法是首先检查设备管理器中是否有 HDC 设备显示，如果没有，尝试更换 USB 口、USB 线，或者重新安装设备驱动；其次，确认设备的 USB 调试功能已开启，并且在设备上允许了电脑的调试授权 。例如在华为设备上，要确保开发者选项中的 USB 调试开关处于打开状态，且设备连接时弹出的授权提示已被确认 。

1. 命令执行失败：比如执行文件传输、应用安装等命令时出现错误提示。以安装应用失败为例，可能是应用安装包损坏、应用签名不一致或者设备存储空间不足等原因导致。解决时，先检查安装包的完整性和正确性，可以重新下载安装包；若涉及签名问题，需要确保应用的签名与设备的要求一致；对于存储空间不足的情况，清理设备上的一些无用文件或卸载不需要的应用，释放足够的存储空间 。

1. HDC 版本不兼容：当设备烧写的是最新镜像，而 HDC 未使用最新版本时，可能会出现连接或命令执行问题。解决方法是及时关注华为开发者官方网站，下载并更新到与设备镜像版本匹配的 HDC 最新版本，以保证工具与设备的兼容性 。

1. 端口被占用：hdc 和 hdc_std 使用同一端口，同时运行会导致端口互相冲突。这种情况下，需要注意只运行其中一个工具。可以通过查看任务管理器，结束正在运行的冲突进程，然后重新启动正确的 HDC 工具 。

五、总结与展望

HDC 交互命令在鸿蒙开发中扮演着举足轻重的角色，从基础的设备连接与信息查询，到复杂的文件传输、应用管理以及系统级的调试操作，它为开发者提供了全方位的支持 。在应用开发阶段，我们可以利用 HDC 快速安装和卸载应用，进行应用状态控制，大大提高了开发和测试的效率；在系统调试方面，通过日志查看和端口转发等命令，能够更精准地定位和解决问题 。无论是个人开发者还是团队开发项目，熟练掌握 HDC 交互命令都能显著提升开发进程。

随着鸿蒙生态的不断发展壮大，我们有理由期待 HDC 在未来会有更多的改进和创新。一方面，在功能上，它可能会进一步拓展与更多设备和系统的兼容性，支持更多复杂的调试场景，例如针对不同硬件平台的深度定制调试功能；另一方面，在使用体验上，或许会朝着更加智能化和自动化的方向发展，减少开发者繁琐的操作步骤，提供更友好的错误提示和解决方案引导 。让我们持续关注 HDC 的发展，不断探索其在鸿蒙开发中的更多可能性，共同推动鸿蒙生态的繁荣发展 。