HarmonyOS(鸿蒙)开发环境搭建

发表于 分类于
以 Windows 为主，说明 DevEco Studio 与 SDK 安装、模拟器验证，以及 uni-app 关联工具链并运行到鸿蒙。

前言

开始写鸿蒙应用前，先要搭好 DevEco Studio 与 HarmonyOS SDK。
路径含中文、虚拟化未开、SDK 组件漏装，都容易让首跑卡在安装或模拟器阶段。
若用 uni-app 出鸿蒙包，还须在 HBuilderX 中关联本机 DevEco 工具链，并完成 harmony-configs 与签名等配置。
下文默认在 Windows 上操作，步骤以当前官方文档为准，版本号请按下载页实际选择。
macOS 仅在相关节末作简要对照。
本文先跑通原生空工程，再说明 uni-app 运行到鸿蒙的配置与验证。

前置要求

请先确认本机大致满足下列条件，具体以华为开发者联盟文档为准。

  1. 系统：Windows 10 / Windows 11（64 位）；macOS 一般为 12 及以上。
  2. 内存：建议 16GB 起，跑模拟器时更推荐 32GB。
  3. 磁盘：SSD，并为 IDE、SDK、模拟器镜像预留足量空间（常需数十 GB 级）。
  4. 路径：安装目录与 SDK、工程路径均使用纯英文、无空格路径。

在 Windows 上可用 PowerShell 快速查看系统与内存概况。

下面命令输出产品名、版本与架构，并汇总物理内存（单位 GB）。

1
2
3
4
5
# 系统信息
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsArchitecture

# 内存信息
[Math]::Round((Get-CimInstance Win32_PhysicalMemory | Measure-Object -Property Capacity -Sum).Sum / 1GB)

若计划使用本地模拟器，还需在 BIOS 中开启 VT-x / AMD-V，并在 Windows 功能中启用 Windows Hypervisor Platform（名称以系统设置为准）。

其它系统： macOS 用 sw_vers 与 sysctl 查看版本与芯片即可，安装方式见下文。

安装 IDE

鸿蒙官方 IDE 为 DevEco Studio，基于 IntelliJ 定制，内置编辑、构建、调试与设备管理能力。

下载

打开华为开发者联盟的 DevEco Studio 下载页，选择与本机对应的安装包。

下载入口示例（以页面实际链接为准）：

1
https://developer.huawei.com/consumer/cn/deveco-studio/

选择 Windows (64-bit) 或 macOS 对应包后下载。
安装包体积较大，网络不稳定时可换时段或换网络重试。

Windows 安装

双击安装包，按向导完成安装。
安装路径建议改为不含中文与空格的目录，例如 D:/DevEco/DevEcoStudio。

安装选项中可勾选创建桌面快捷方式，以及将 bin 加入 PATH（便于命令行调用相关工具）。
安装完成后可直接启动 DevEco Studio。

首次启动若提示导入设置，一般选择不导入即可。
主题与外观可按向导默认或稍后在设置中调整。

macOS 安装

将下载的 dmg 打开后，把 DevEco Studio 拖入 Applications。
首次启动建议在访达中右键选择「打开」，以便通过系统安全提示。

配置 SDK

首次进入 IDE 后，需要登录华为账号并安装 HarmonyOS SDK。
账号需完成开发者实名认证，否则部分下载与调试能力可能受限。

登录与路径

在欢迎页或设置中登录华为开发者账号。
常见入口为 File -> Settings -> HarmonyOS SDK（macOS 上多为 DevEco Studio -> Settings）。

将 SDK 存储路径设为纯英文目录，例如 D:/HarmonyOS/SDK。
路径含中文或空格时，后续同步与编译更容易出现难排查错误。

模拟器

没有真机时，可用 Device Manager 安装模拟器引擎并创建虚拟设备。

  1. 打开 Tools -> Device Manager。
  2. 按提示安装模拟器相关组件。
  3. 新建设备，类型可选 Phone，API 与已安装 SDK 对齐。
  4. 内存建议给足（例如 4GB 档，以向导可选值为准），分辨率可按常用手机规格选择。

创建完成后先启动一次，确认能进入桌面。
若启动失败，优先排查虚拟化是否开启、Hyper-V / Windows Hypervisor Platform 是否冲突或未启用，以及磁盘剩余空间是否充足。

创建工程

环境就绪后，用空模板创建工程，用来验证工具链是否可用。

新建项目

在欢迎页选择创建 HarmonyOS 工程，模板选 Empty Ability。
应用模型选择当前推荐的 Stage。

配置项建议如下（名称可自定，路径仍保持纯英文）。

项 示例
Project name HelloHarmony
Bundle name com.example.helloharmony
Save location D:/Projects/HelloHarmony
Compile SDK 本机已安装的目标 API
Module name entry

点击完成后等待工程同步结束。
首次同步可能较久，属正常现象。

改首页文案

主页面一般在 entry/src/main/ets/pages/Index.ets。
可将默认文案改成自定义字符串，便于确认运行的是本工程。

下面示例在首页显示一行欢迎文字（具体组件 API 以你工程模板为准，若编译报错请按模板原写法微调）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Entry
@Component
struct Index {
  @State message: string = 'Hello HarmonyOS';

  build() {
    RelativeContainer() {
      Text(this.message)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
    }
    .height('100%')
    .width('100%')
  }
}

验证

在设备下拉框中选择已启动的模拟器，或已连接的真机，然后点击运行。
工程能安装并显示刚才的文案，即说明 IDE、SDK 与设备链路基本打通。

也可在 IDE 终端中进入工程目录后执行构建命令做编译自检（命令名与参数以当前 DevEco / hvigorw 文档为准）。

下面示例在工程根目录触发一次组装构建（若脚本名不同，以工程内实际文件为准）。

1
hvigorw assembleHap

若同步失败，回到 Settings -> HarmonyOS SDK 确认目标 API 与 Toolchains 已安装完整，并检查工程路径是否含中文。

uni-app

原生工具链就绪后，可用 HBuilderX 把 uni-app（Vue3）项目运行到鸿蒙模拟器或真机。
鸿蒙端不支持 Vue2，也不支持 plus；版本组合以 uni-app 运行和发行 为准。

环境要求

在已安装并配置好 DevEco 的前提下，再准备 HBuilderX。

  1. HBuilderX：建议 4.24+（鸿蒙运行能力自此版本起提供，宜用较新正式版）。
  2. DevEco Studio：版本需与当前 HBuilderX 匹配（例如较新的 HX 常要求更高 DevEco，以官网兼容表为准）。
  3. 模拟器：Windows x86 上跑 uni-app 鸿蒙时，系统镜像一般需 API 19+（文档常建议 API 20+）；真机要求相对宽松，仍须满足文档中的系统版本下限。
  4. 工程：使用 Vue3 的 uni-app 项目；路径尽量短、纯英文，避免中文与特殊字符。

HBuilderX 会依赖 DevEco 自带的鸿蒙工具链完成构建与安装。
模拟器仍须在 DevEco 的 Device Manager 中启动，HX 本身不能单独拉起模拟器。

关联 DevEco

打开 HBuilderX，进入 工具 -> 设置 -> 运行配置，在鸿蒙运行配置中填写本机 DevEco Studio 安装目录。
填根目录即可，不必点到某个 exe。

也可在 HX 的 Settings.json 中写入路径（键名以你本机 HX 为准，常见为 harmony.devTools.path）。

下面示例将工具链路径指向 D:/DevEco/DevEcoStudio，请改成你的实际安装目录。

1
2
3
{
  "harmony.devTools.path": "D:/DevEco/DevEcoStudio"
}

保存后新开或重载配置，再执行「运行到鸿蒙」。
若未手动配置，部分版本会尝试自动检测本机 DevEco 并写入。

工程目录

默认调试产物在 unpackage/dist/dev/app-harmony，发行产物在 unpackage/dist/build/app-harmony。
Windows 上路径过长容易导致鸿蒙工具链构建失败，因此项目根路径宜短。

从 HBuilderX 4.61+ 起，可在 .hbuilderx/launch.json 把鸿蒙工程目录指到更短的盘符路径，以降低路径长度限制的影响。

下面示例把调试与发行用的鸿蒙工程目录分别指到短路径（目录可不预先存在，HX 会按需创建）。

1
2
3
4
5
6
7
8
9
10
{
  "version": "1.0",
  "configurations": [
    {
      "type": "uni-app:app-harmony",
      "distPathDev": "D:/harmony-project-dev",
      "distPathBuild": "D:/harmony-project-build"
    }
  ]
}

harmony-configs

首次「运行到鸿蒙」时，HX 会在项目根目录生成 harmony-configs。
之后凡鸿蒙侧包名、签名、权限等工程级调整，都应写在该目录，构建时会覆盖到生成的鸿蒙工程中。

常用调整包括：

  1. 包名：在 harmony-configs/AppScope/app.json5 中修改 bundleName（需与证书、AGC 应用信息一致）。
  2. 签名：在 harmony-configs/build-profile.json5 中配置 app.signingConfigs（4.61+ 也可在运行对话框里交互配置）。
  3. 模块权限等：按需改 harmony-configs 下对应 json5，写法参照鸿蒙工程文档。

HX 升级后若提示模板与内置版本不匹配，按提示把需要更新的内容合并进 harmony-configs，避免旧配置拖垮新工具链。

运行到鸿蒙

  1. 在 DevEco 中启动已创建的模拟器，或连接已开启调试的鸿蒙真机。
  2. 用 HBuilderX 打开 Vue3 的 uni-app 工程。
  3. 菜单选择 运行 -> 运行到手机或模拟器 -> 运行到鸿蒙。
  4. 选择目标设备；真机首次需配置调试证书（4.61+ 可点「配置调试证书」，支持自动申请）。
  5. 等待编译、组装鸿蒙工程、安装并启动。

运行对话框里通常还有缓存策略（差量更新 / 强制用缓存 / 清空缓存）与打包模式（debug / release）。
升级 HX 后首次运行，或出现莫名其妙的旧产物问题时，可先选清空缓存再构建。

构建阶段 HX 会编译当前项目，将产物与 harmony-configs 合并进鸿蒙工程目录，再调用 DevEco 工具链安装到设备。
控制台日志在较新 HX 上可回源到业务代码，便于排查。

证书与分发

真机调试与发行都需要签名。
常用文件为 .p12（私钥库）、.cer（证书）、.p7b（Profile）；包名须一致。
HBuilderX 4.61+ 可在「运行到鸿蒙」流程里配置或自动申请调试证书。
也可在 DevEco 申请后，把 signingConfigs 拷到 harmony-configs/build-profile.json5（含 material 目录）。

项 调试证书 发布证书
用途 开发真机调试 上架与正式签名
设备 Profile 绑定 UDID 一般不绑设备
微信/网盘直接传包 通常装不上 通常装不上

鸿蒙侧载很严，调试包、发布包直接发给别人点开，一般都装不上。
别人要能装，按目标选通道：

目标 做法
普通用户 上架华为应用市场
测试同学自助安装 AGC（AppGallery Connect）官方内测 / 邀请测试等
开发同事联调 调试证书：绑 UDID + 开开发者模式 + hdc / IDE，三步都要

调试联调

三步是一条链路，不是三选一：

  1. 把对方设备 UDID 写入调试 Profile 并重新签名（未登记则 hdc 也会失败）。
  2. 对方开启开发者模式与 USB / 无线调试（只开开发者模式 ≠ 可随意侧载）。
  3. 用电脑 hdc、DevEco 或 HBuilderX「运行到该设备」安装（只发文件给对方点开通常不行）。

hdc（HarmonyOS Device Connector）类似安卓 adb，随 DevEco / SDK 提供，用于连设备装包、看日志等。
设备已连接授权后，可先列出目标再安装本地 hap（路径按实际修改）。

下面两条命令依次查看已连接设备，并将指定 hap 安装到当前设备。

1
2
hdc list targets
hdc install D:/packages/app-debug.hap

AGC 内测

AGC 是华为应用市场开发者后台，负责创建应用、证书、上传包与上架。
「内测」指尚未全网上架时，用官方测试分发让指定人或设备下载安装（指定设备发布、邀请测试等，以后台为准）。
需要对方自己点链接安装时，走 AGC，不要只传本地安装包。

扩展

真机调试

开启开发者选项与调试开关后，用 USB 或无线调试连接电脑，并在手机上信任该计算机。
设备应出现在 DevEco Device Manager 或 HBuilderX 运行列表中。
调试包安装仍须满足上文「证书与分发」中的联调三步。

常见问题

  1. 路径含中文、空格或过长：缩短项目路径，或用 launch.json 指定短路径的 distPathDev / distPathBuild。
  2. 模拟器无法启动：检查 BIOS 虚拟化、Windows 虚拟机平台相关功能与剩余磁盘。
  3. Windows 模拟器跑不起 uni-app：确认模拟器镜像为文档要求的 API 19+（建议更高）。
  4. SDK 下载中断：换网络后在 SDK 管理页对未完成项重新 Apply。
  5. 构建提示 Node 版本异常：改回使用 IDE 内置 Node.js。
  6. HX 找不到工具链：检查 运行配置 中的 DevEco 安装目录，或 harmony.devTools.path。
  7. 真机 / 传包装不上：核对签名与包名；调试包须 UDID 在 Profile，并用 hdc / IDE 安装。只开开发者模式或只发文件通常不够；给别人自助装请走 AGC 或应用市场。

总结

  1. 用纯英文路径安装 DevEco Studio，登录华为开发者账号。
  2. 在 HarmonyOS SDK 中安装目标 API、Toolchains 等必要组件，优先用内置 Node。
  3. 通过 Device Manager 创建并启动模拟器，或连接已开启调试的真机。
  4. 用 Empty Ability 创建工程并运行，确认原生工具链可用。
  5. 在 HBuilderX 中配置 DevEco 路径，用 Vue3 工程执行「运行到鸿蒙」，按需维护 harmony-configs。
  6. 证书：调试联调 = 绑 UDID + 开发者模式 + hdc / IDE；发布证书用于上架。直接传包通常装不上，自助安装走 AGC 或应用市场。

版本与菜单文案会随 IDE 升级变化。
遇差异时以华为开发者联盟文档与 uni-app 鸿蒙运行说明 为准。