从下载 DevEco 到 hdc list targets 看到设备——我配齐鸿蒙 PC 开发环境的那一晚

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

这不是"DevEco 安装指南"——那种官方文档写得比谁都全。

这是一个本机已经装了一堆乱七八糟开发工具的中年程序员，第一次配鸿蒙 PC 开发环境时的真实操作记录：哪一步耗了多久、哪个安装包应该从哪个站点下、哪些环境变量必须改、哪些"明明官方文档没写"的小坑会让你卡半小时。

写给那种"先装上、晚点再读文档"的开发者。

在这里插入图片描述
在这里插入图片描述

这篇文章给谁看

如果你符合下面任意一条，就可以接着读：

  • 拿到一台新 Mac/Win 电脑，今晚想把鸿蒙 PC 开发环境配完
  • 装过 Android Studio、Xcode、IntelliJ、VS Code 任意一个，所以对"折腾 IDE"心理有预期
  • 不想读 80 页官方安装手册，只想要"装哪个、装哪、配什么"的最短路径
  • 出现过 hdc: command not found 然后骂了一句

一、那天晚上 19:30，先把要装的东西列出来

我那天晚上下班回家，吃完饭打开 MacBook Pro（M3 Max / macOS 26），决定把鸿蒙 PC 开发环境配齐。

在开始之前，我先列了张清单——这一步是关键，不列清单直接动手会被各种依赖关系绕死：

工具 用途 大概体积
DevEco Studio 鸿蒙官方 IDE（基于 IntelliJ） ~2 GB
OHOS SDK API Level 17 / 23 SDK ~3 GB（每个 API 等级）
HarmonyOS NDK（含在 SDK 里） C/C++ Native 开发 （含在 SDK 里）
Node.js hvigor 构建系统依赖 20 MB
OHPM OpenHarmony 包管理器 20 MB
hdc adb 的鸿蒙对应物 含在 SDK 里
华为开发者账号 调试签名必需 0 GB / 1 小时实名

总计磁盘占用 ≈ 8 GB，我预留了 15 GB 空间防意外。

⚠️ 提前提醒：华为开发者账号实名认证要等审核，国内一般 1-3 小时，海外/特殊情况可能要 1-2 天。先把账号注册了再开始下载东西，并行节省时间。我那天就是一边等审核一边下 DevEco。

二、19:35 - 19:50：注册华为开发者账号（这事先开）

为什么先注册？因为后面真机调试签名 100% 需要这个账号——而且自动签名要现拉证书，所以账号要在自动签名之前就绪。

路径：

华为开发者联盟 (https://developer.huawei.com)
  → 个人账号注册
  → 实名认证（身份证正反面 + 人脸识别）
  → 等审核短信

真实耗时：我那天 19:35 提交，19:51 收到审核通过短信——比预想的快。

不过这个时间不稳定——我有同事第二天上午才收到。所以建议你一上来先提交，别等到要签名的时候才发现没账号。

三、19:40 - 20:05：DevEco Studio 下载

下载地址

在这里插入图片描述

官方下载页：https://developer.huawei.com/consumer/cn/deveco-studio/

注意两件事：

  1. 要登录账号才能下（所以前面注册账号确实是关键路径）
  2. 页面会自动检测你的 OS 推荐对应版本——macOS Apple Silicon 是 .dmg，Intel Mac 也是 .dmg（别下错架构），Windows 是 .exe

我撞到的第一件事

我点了下载按钮之后没反应。

刷新页面、换浏览器，没反应。

后来发现是因为触发了华为登录态校验——账号注册后要等几分钟登录态生效才能下载。我等了大概 5 分钟重试就好了。

下载速度

国内电信光纤实测：

DevEco-Studio-5.1.0.xxx.dmg  约 2.1 GB
平均下载速度：约 18 MB/s
耗时：约 2 分钟

如果你下不动（速度 < 1 MB/s），换个时间——华为站点在工作日 22:00-23:00 是高峰，周中半夜 1 点 / 周末上午速度最稳。

四、20:08 - 20:18：装 DevEco

.dmg 装一般 IDE 一样的体验：拖到 Applications 完事。

第一次启动会做的事

  1. 检测 Node.js——没装会提示"建议先装"
  2. 检测 SDK Manager——没有会引导下载
  3. 登录华为账号——这一步把刚注册的账号填进去

我那天撞到的事

DevEco 第一次启动的时候我同时还开着 IntelliJ IDEA 和 Android Studio——它们三个都基于 IntelliJ 平台，缓存目录会冲突。

具体表现：DevEco 启动后某些 IDE 设置看着像 Android Studio 的（侧栏、配色），但功能又是鸿蒙的——后来发现是 IDEA 的 ~/Library/Application Support/JetBrains/ 缓存被它复用了一部分。

解决方法：DevEco 启动后立刻 File → Manage IDE Settings → Restore Defaults，把它从 IDEA 缓存里"独立"出来。

五、20:20 - 20:32：装 Node.js（这步很多人栽）

推荐版本

Node.js v20.18.1（DevEco 5.1 实测最稳的版本）。

不要装最新版（v22+），鸿蒙的 hvigor 对最新 Node 兼容不好——我看到至少 3 个同事栽在这里：装了 Node 23，跑 build 报 crypto.hash is not a function，查了半天才发现是 Node 版本太新。

怎么装最干净

macOS / Linux 用 nvm（强烈推荐，因为你后面可能会同时用多个 Node 版本）：

# 装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重启终端，然后装指定版本
nvm install 20.18.1
nvm use 20.18.1
nvm alias default 20.18.1   # ← 设默认，避免重启终端后版本回退

# 验证
node -v   # 应该输出 v20.18.1
npm -v

Windows：建议用 nvm-windows，逻辑一样。别直接装官方 .msi——后面想换版本会很痛苦。

我那天撞到的事

我之前用 brew install node 装过一次 Node 22。这次 nvm install 20.18.1 之后，发现终端默认还是 Node 22——因为 brew 装的 node 在 /opt/homebrew/bin/node，PATH 优先级高于 nvm 的。

解决方法：

brew uninstall --ignore-dependencies node    # 卸 brew 的版本
# 或者临时方案：每个新终端先 nvm use 20.18.1

记得卸完之后重启终端再验证 node -v。

六、20:35 - 20:50：装 OHPM（鸿蒙包管理器）

OHPM 是 OpenHarmony Package Manager 的简写——你可以把它理解为鸿蒙的 npm。

装 OHPM 有两种路子

路子 A：让 DevEco 自动装（推荐）

DevEco 5.1 启动后会引导你下 OHPM，点确认按钮就行，它会装到 DevEco 自己的目录里：

macOS:   ~/Library/Huawei/ohpm/
Windows: %USERPROFILE%\AppData\Local\Huawei\ohpm\

路子 B：手工装（懂的话）

# 1. 下 ohpm 离线包：https://developer.huawei.com/consumer/cn/download/
# 2. 解压
tar -xzf commandline-tools-mac-x64-xxx.tar.gz
cd command-line-tools/ohpm/bin

# 3. 初始化
./init
# 它会提示输入安装路径

我自己走的路子 A——DevEco 帮你做最省心。

必须改的事：换 OHPM 镜像源

OHPM 默认源是华为海外的，国内访问极不稳定。装完立刻换镜像：

ohpm config set registry https://ohpm.openharmony.cn/ohpm/

# 验证
ohpm config get registry

这一步不做的话，后面拉任何依赖都会卡 3-5 分钟。我亲眼看到一个同事第一次跑工程 Resolving dependencies 卡了 12 分钟——查了一圈才发现就是这个。

七、20:55 - 21:35：装 SDK（这是大头）

进入 SDK Manager

DevEco 主界面：

File → Settings (macOS: DevEco Studio → Settings) → SDK

进去之后会看到一个表格——左边是 API 等级（API 9 / API 11 / API 17 / API 20 / API 23 …），右边勾选要装的组件（Public SDK / Native / Toolchains / Previewer）。

装哪几个

最小集（不做 native C++ 开发）：

  • ✅ Public SDK（必装）
  • ✅ Toolchains（必装，含 hdc）
  • 🟦 Native（要写 C++ / 接 NAPI / 用 Electron 才装）
  • 🟦 Previewer（可选，本机预览）

API 等级选哪个：

你的目标 建议勾选
上架到当前主流鸿蒙 PC API 17（HarmonyOS 5.0.5）+ API 20（6.0）
最新设备 / 6.1 真机调试 上面 + API 23（HarmonyOS 6.1）
做 Electron 适配 必勾 Native！
做 Qt 交叉编译适配 Native 必勾

我那天勾的是 17 + 20 + 23 三个 API 等级 + Native + Toolchains，总下载量大约 7 GB。

下载有多慢

国内电信光纤实测：

API 17:  约 2.8 GB / 7 分钟
API 20:  约 3.1 GB / 8 分钟
API 23:  约 3.3 GB / 9 分钟
Native:  约 800 MB / 2 分钟
合计：    约 10 GB / 26 分钟

这一步可以挂着去喝杯水。我下载的时候顺便去把鸿蒙 PC 设备插上电、打开了开发者模式（见下一节）。

装完 SDK 的真实路径

知道路径很重要——很多文档不告诉你SDK 装哪了：

macOS:   ~/Library/Huawei/Sdk/openharmony/<api_level>/
Windows: %USERPROFILE%\AppData\Local\Huawei\Sdk\openharmony\<api_level>\

进去看，每个 API 等级是一个独立文件夹：

~/Library/Huawei/Sdk/openharmony/12/
  ├── ets/                    # ArkTS 框架
  ├── js/                     # 老的 JS 框架
  ├── native/                 # NDK
  ├── previewer/              # 预览器
  ├── toolchains/             # hdc / 签名工具等 ← 这是你要加进 PATH 的
  └── ...

八、21:38 - 21:45：把 hdc 加进 PATH（官方文档没强调的事）

这是最容易被忽视的一步——但它直接决定你以后在命令行下能不能用 hdc。

问题现场

装完 SDK，立刻打开终端：

$ hdc list targets
zsh: command not found: hdc

——是的，默认 hdc 不在 PATH 里。

解决方案

把 toolchains 路径加到 shell 的 PATH 里。

macOS / Linux（zsh）：

echo 'export PATH="$HOME/Library/Huawei/Sdk/openharmony/12/toolchains:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
which hdc
# /Users/yourname/Library/Huawei/Sdk/openharmony/12/toolchains/hdc

hdc -v
# Ver: 3.0.0a

Windows：

  1. 右键"此电脑" → 属性 → 高级系统设置 → 环境变量
  2. 编辑用户变量 Path，新增：
    %USERPROFILE%\AppData\Local\Huawei\Sdk\openharmony\12\toolchains
  3. 重启 PowerShell / cmd

我撞到的小坑

我系统里同时装过 Android SDK，Android 的 adb 和鸿蒙的 hdc 在思维上很像但命令不一样。

第一次连鸿蒙 PC 时我下意识打 adb devices，啥也没出来——但我以为是 USB 出问题，又拔插重启了 3 次。

后来才反应过来——鸿蒙不是 Android，要用 hdc：

adb devices      ← Android 的，鸿蒙连不上
hdc list targets ← 鸿蒙的，对！

把这两个命令的差异贴在你显示器侧面，能省后续很多麻烦。

九、21:48 - 21:55：连鸿蒙 PC 设备（USB / Wifi 两种方式）

先打开设备端的"开发者模式"

鸿蒙 PC 的开发者模式藏在比较深的地方：

设置 → 关于本机
  → 软件版本 → 连续点 7 次
  → 输入锁屏密码
  → 提示"已进入开发者模式"

然后：
设置 → 系统与更新 → 开发者选项
  → 打开"USB 调试"

——和 Android 一模一样的逻辑，老 Android 开发者闭着眼睛能找到。
在这里插入图片描述

方法 A：USB 连接

# 数据线连主机和鸿蒙 PC
hdc list targets

# 期望输出：
8A123456789ABC

如果输出 [Empty]，第一步先看物理连接——华为 PC 的 USB-C 口区分"充电"和"数据"，用错口子是常见问题。

方法 B：Wifi 无线调试（强烈推荐）

USB 在鸿蒙 PC 上有个明显问题——断开次数多了驱动会抽风，重启才能恢复。所以我后来基本走 Wifi。

# 1. 先用 USB 连上一次，开启 TCP 模式
hdc tmode port 5555

# 2. 在设备上看 IP（鸿蒙 PC 状态栏可以看到 wifi 详情）
#    假设是 192.168.1.42

# 3. 拔掉 USB，无线连接
hdc tconn 192.168.1.42:5555

# 4. 验证
hdc list targets
# 应该看到 192.168.1.42:5555 [Connected]

亲测稳定——我已经一周没插 USB 了，每天开机 hdc 还在。

十、22:00 - 22:15：第一次 build 并部署

到这一步，所有工具都装好了。建议立刻拿一个空的鸿蒙工程跑一遍——验证整条链路。

创建空工程

DevEco → File → New → Create Project
  → 选 "OpenHarmony" 模板
  → Empty Ability
  → 填项目名、bundleName
  → Finish

第一次 Sync

DevEco 会自动跑 hvigor sync 拉依赖。这一步最容易出问题——

错误 原因 解决
Resolving dependencies 卡 10 分钟+ OHPM 源没换 第六节最后那个 ohpm config set registry
compatibleSdkVersion not supported 工程要求的 API 等级你没装 回 SDK Manager 装对应等级
Cannot find module @ohos/xxx OHPM 缓存损坏 rm -rf ~/.ohpm/cache && ohpm install
Hvigor 报 crypto.hash is not a function Node 版本太新 nvm 切到 20.18.1

签名

File → Project Structure → Signing Configs
  → 勾"Automatically generate signature"
  → 它会让你登录刚才注册的华为账号
  → 几秒钟后证书自动配好

第一次 Run

设备已经通过 hdc 连接的话，DevEco 右上角设备下拉框里能看到。点 ▶ Run。

第一次部署慢（30 秒-1 分钟），等出现一个空白窗口就成功了。

那天我 22:14 看到那个空白窗口的时候，特意截了张图——这是我桌面环境第一次完整运行起来的纪念。

十一、22:20 之后：把一些"晚一点会用到"的事也做了

不是必须，但建议一晚做完，省得后面打断思路：

11.1 装一些 DevEco 必备插件

DevEco 自带功能足够日常用，但有几个插件强烈推荐先装上：

  • HarmonyOS Lint——鸿蒙代码规范检查
  • GitToolBox（IDEA 通用）——Git 状态行内显示
  • Rainbow Brackets——括号配色

路径：DevEco → Settings → Plugins → Marketplace

11.2 配置 hilog 实时跟踪别名

我懒得每次都打长长的命令：

# 在 ~/.zshrc 加：
alias hlog='hdc shell hilog | grep -iE'

# 以后调试这么用：
hlog "myapp|cppcrash"

11.3 把签名证书路径备份

DevEco 自动签名生成的证书在：

~/.ohos/config/

这里有你的私钥，丢了就要重新申请。我做的事是：

# 备份到自己的私有云盘
cp -r ~/.ohos/config/ ~/iCloud/backup/ohos-cert/

但不要传到 GitHub / 公共仓库——我看过同事这么干，最后只能重申账号。

11.4 在 DevEco 里启用"国内镜像"

DevEco → Settings → Build → Build Tools → Hvigor
  → 勾"Use mirror"或填镜像地址

不勾的话每次 hvigor build 会去访问海外某些 CDN，特别慢。

十二、22:35：环境配齐之后我做的最后一件事

把整个环境的状态截图存档，写了一份 ~/notes/HarmonyOS_dev_env.md，记录：

DevEco Studio:  5.1.0.825
Node.js:        20.18.1 (via nvm)
OHPM:           5.0.18 (registry: openharmony.cn)
SDK 装了:        API 17 / 20 / 23
设备:           MateBook Pro (192.168.1.42:5555)
华为账号:        dev***@xxx.com
证书有效期至:    2026-09-XX

为什么记这个：这玩意儿过半年你就忘了。下次有事要查"我装的是哪个版本"就直接 cat ~/notes/HarmonyOS_dev_env.md。

很多人懒得记，结果半年后系统升级、IDE 升级、环境变了，根本不知道之前正常的状态是啥样——出问题就只能从头摸。

十三、一些"如果重来一次我会怎么做"的建议

写到这里，我那天晚上从 19:30 到 22:35 大概 3 小时——其中真正必须做的事大约 1.5 小时，剩下都是踩坑+查文档。

如果你今晚也要配，下面是我总结的"如果重来一次会怎么做"：

13.1 顺序应该这样

1. 注册华为账号（先点提交等审核，全程才 15 分钟，但要排在最前）
   ↓
2. 装 Node.js 20.18.1（别用 brew 直接装，用 nvm）
   ↓
3. 下 DevEco Studio（这一步耗时最长，挂着）
   ↓
4. DevEco 装好后让它引导装 OHPM + SDK
   ↓
5. 装完 SDK 立刻把 hdc 加 PATH 并换 OHPM 镜像
   ↓
6. 设备开发者模式 + Wifi 调试配置
   ↓
7. 跑空工程跑一遍验证

13.2 提前下载几个东西

☐ Node.js v20.18.1 安装包（备用，如果 nvm 不顺利）
☐ DevEco Studio 离线安装包
☐ 当前设备的 OS 版本号（hdc shell param get const.product.software.version）
☐ MateBook 的网线/数据线（USB-C 数据线，不是只能充电的那种）

13.3 几个"千万别做"的事

❌ 不要在 brew/apt 装的 Node 上跑鸿蒙 build——版本不可控
❌ 不要跳过 OHPM 换源——会让你以为是"鸿蒙慢"，其实是源慢
❌ 不要把 ~/.ohos/config/ 提交到 Git——这里有私钥
❌ 不要拿别人的 build-profile.json5 直接用——里面的证书路径只在他本机有效
❌ 不要装超过 3 个 API 等级的 SDK——磁盘占用很快上 30 GB

13.4 几个"早做晚做都要做"的事

✅ 注册华为账号（越早越好）
✅ 加 hdc 到 PATH（不加就一直 command not found）
✅ 换 OHPM 镜像（这个 60 秒的事能节省你几小时）
✅ Wifi 调试模式（USB 一段时间后就会抽风）
✅ 记录环境状态到笔记（过半年你会感激今天的自己）

写在最后

配环境这件事，对绝大部分开发者来说都是"一次性"的——配完之后开始写代码，几个月不会再去碰这些东西。

所以这种文章在配的当下读起来"啰嗦"，但你配过两三个 IDE 环境的人都知道——多半我们当年都为某一步卡过半天，然后"再也不想配第二次"。

那就把这个晚上的折腾整理出来，希望今晚正在配环境的你能少花 1-2 小时。

如果你卡在某一步，欢迎来 https://harmonypc.csdn.net/ 问——大概率有人撞过同一面墙。

附录 A：本文涉及命令汇总（可复制）

# ===== Node.js =====
nvm install 20.18.1 && nvm use 20.18.1 && nvm alias default 20.18.1

# ===== OHPM 换源 =====
ohpm config set registry https://ohpm.openharmony.cn/ohpm/
ohpm config get registry

# ===== PATH 加 hdc（macOS / zsh） =====
echo 'export PATH="$HOME/Library/Huawei/Sdk/openharmony/12/toolchains:$PATH"' >> ~/.zshrc
source ~/.zshrc
which hdc

# ===== 设备连接 =====
hdc list targets
hdc shell param get const.product.software.version    # 看 ROM 版本
hdc tmode port 5555                                    # 开 TCP 调试
hdc tconn 192.168.1.42:5555                            # Wifi 连接

# ===== 常用调试命令 =====
hdc shell hilog                                        # 实时日志
hdc shell aa start -a EntryAbility -b com.your.bundle  # 启动应用
hdc shell bm uninstall -n com.your.bundle              # 卸载应用
hdc file send local.txt /data/local/tmp/               # 推文件
hdc file recv /data/log/faultlog/xxx ./                # 拉文件

附录 B：常见命令速查（贴在显示器侧面）

Android (adb) HarmonyOS (hdc) 作用
adb devices hdc list targets 列出连接设备
adb install x.apk hdc install x.hap 安装应用
adb uninstall x hdc shell bm uninstall -n x 卸载
adb logcat hdc shell hilog 看日志
adb shell hdc shell 进设备 shell
adb push f /sdcard/ hdc file send f /data/local/tmp/ 推文件
adb pull /sdcard/f . hdc file recv /data/local/tmp/f . 拉文件
adb tcpip 5555 hdc tmode port 5555 开 TCP 调试
adb connect ip hdc tconn ip:5555 网络连接

附录 C：本机环境状态模板

写这玩意的目的：配完之后过半年还能知道自己当时配的是啥。建议存在 ~/notes/HarmonyOS_dev_env.md：

# HarmonyOS 开发环境快照

配置日期：2026-06-10
配置主机：MacBook Pro M3 Max / macOS 26.0

## 工具版本
- DevEco Studio:  5.1.0.xxx
- Node.js:        20.18.1 (via nvm)
- OHPM:           5.0.xx (registry: openharmony.cn)
- hdc:            3.0.0a

## SDK
- 已装 API:       17, 20, 23
- 装的组件:        Public SDK + Native + Toolchains
- 安装路径:       ~/Library/Huawei/Sdk/openharmony/

## 设备
- 主力机型:       MateBook Pro HAD-W24
- 系统版本:       HarmonyOS 6.1.0 / API 23
- 调试方式:       Wifi (192.168.1.42:5555)

## 账号 / 证书
- 华为账号:       dev***@xxx.com
- 调试证书路径:    ~/.ohos/config/
- 已加调试设备 UDID: xxxxxxx (MateBook), yyyyyyy (备用机)
- 证书有效期:     至 2026-09-xx

## 镜像 / 源
- OHPM:          https://ohpm.openharmony.cn/ohpm/
- npm:           https://registry.npmmirror.com/

## 已知问题 / 备忘
- 同时装 Android SDK 时，确认 hdc 在 PATH 优先级靠前
- 不要把 ~/.ohos/config/ 提交到 Git

在这里插入图片描述

# list # harmonyos # 数据结构
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

瑞芯微RK3576落地智能农业新生态，鸿蒙农机平板应用场景拓展

avatar 人工智能6S服务平台
cover

【共创季稿事节】鸿蒙原生ArkTS布局方式之ColumnStart垂直排列

avatar 人工智能6S服务平台
cover

鸿蒙 Intents Kit 是什么，它和普通 Deep Link 的差别在哪

avatar 人工智能6S服务平台