一、前言

随着 HarmonyOS 5 的持续演进，2026 年的鸿蒙开发环境相比早期版本已经发生了较大变化：

• DevEco Studio 已集成 HarmonyOS SDK、Node.js、Hvigor 等核心工具，无需再单独安装 SDK。
• ArkTS 已成为 HarmonyOS 应用开发的主流语言。
• DevEco Studio 5.x 成为 HarmonyOS 5 官方推荐开发工具。

很多初学者第一次安装都会遇到：

• SDK 下载失败
• Emulator 无法启动
• HDC 无法识别手机
• 华为账号登录失败
• Preview 无法预览
• Build Failed
• hvigor 报错
• ohpm 下载失败

本文将从 零开始，完整介绍 HarmonyOS 5 开发环境搭建，并总结常见问题及解决方案。

---

二、开发环境要求

1、操作系统

官方支持：

Windows

推荐：

• Windows 11（22H2 及以上）

兼容：

• Windows 10 64 位

---

macOS

推荐：

• macOS 15

兼容：

• macOS 12+
• Intel
• Apple Silicon（M 系列）

官方均提供支持。

---

2、硬件推荐

项目	最低	推荐
CPU	i5	i7/Ryzen7
内存	8GB	16GB+
SSD	50GB	100GB+
分辨率	1280×800	1920×1080

如果需要运行 Emulator，建议至少 16GB 内存。

---

三、安装 DevEco Studio

目前官方推荐使用 DevEco Studio 5.x。安装包已集成 HarmonyOS SDK 和相关工具链，无需额外下载 SDK。

安装步骤：

1. 下载对应系统版本。
2. Windows 双击 .exe，macOS 将应用拖入 Applications。
3. 首次启动时选择 Do not import settings。
4. 等待初始化完成。

---

四、首次启动配置

首次启动建议：

• 不导入旧配置
• 使用默认主题
• 保持默认插件
• 首次联网完成依赖同步

---

五、HarmonyOS SDK

当前版本特点：

• SDK 已内置
• ArkTS SDK 已集成
• Toolchains 已集成
• Emulator 可按需安装

可通过 SDK Manager 查看和更新 SDK。

---

六、创建第一个项目

推荐模板：

Application
    └── Empty Ability

填写：

• Project Name
• Bundle Name
• Save Location
• Compile SDK
• Device Type

点击 Finish，等待同步完成。

---

七、项目目录解析

常见目录：

AppScope/

entry/

resources/

ets/

oh_modules/

build-profile.json5

oh-package.json5

说明：

• AppScope：应用级配置
• entry：主模块
• resources：资源
• ets：ArkTS 源码
• oh_modules：依赖

---

八、运行模拟器

首次运行：

Run

如果没有设备：

Device Manager

创建：

Phone Emulator

等待启动即可。

---

九、真机调试

步骤：

1. 手机开启开发者模式
2. 开启 USB 调试
3. 连接 USB
4. HDC 自动识别
5. 点击 Run

---

十、HDC 工具

查看设备：

hdc list targets

安装：

hdc install xxx.hap

卸载：

hdc uninstall 包名

日志：

hdc shell hilog

---

十一、Preview 预览

ArkUI 支持：

• 实时预览
• 多设备预览
• 深色模式
• 横竖屏切换

大幅提升 UI 开发效率。

---

十二、常见环境变量

虽然新版通常无需手动配置，但以下变量在部分高级场景仍可能用到：

DEVECO_HOME
JAVA_HOME
PATH

---

十三、Node.js

新版 DevEco Studio 已集成 Node.js 运行环境；独立工具（如 DevEco Code）则建议使用较新的 Node.js 版本。

验证：

node -v

---

十四、OHPM

安装依赖：

ohpm install

更新：

ohpm update

---

十五、Hvigor

构建：

hvigor assemble

清理：

hvigor clean

---

十六、Build 流程

ArkTS
↓

编译

↓

ABC

↓

打包

↓

HAP

↓

安装

↓

运行

---

十七、签名

开发阶段：

Debug 签名。

发布：

Release 签名。

---

十八、运行第一个页面

修改：

pages/Index.ets

例如：

build() {
  Column() {
    Text("Hello HarmonyOS")
      .fontSize(30)
  }
}

点击 Run 即可看到效果。

---

十九、常见问题汇总

SDK 下载失败

• 检查网络
• 使用 SDK Manager 重试

Emulator 启动失败

• 开启 CPU 虚拟化
• Windows 避免与 Hyper-V 冲突

HDC 找不到设备

hdc list targets

确认 USB 调试已开启。

ohpm 超时

可尝试重新同步依赖并检查网络。

Build Failed

建议：

Clean Project

然后重新构建。

---

二十、开发建议

推荐学习路线：

1. ArkTS 语法
2. ArkUI 基础组件
3. 状态管理（@State、@Prop、@Link 等）
4. 页面路由
5. 网络请求
6. 数据持久化
7. 权限管理
8. 多设备开发
9. 性能优化
10. 上架发布

---

二十一、推荐开发工具

• DevEco Studio
• HarmonyOS Emulator
• HDC
• Hvigor
• OHPM
• DevEco Code（AI 辅助开发）

---

二十二、总结

完成上述步骤后，你将具备完整的 HarmonyOS 5 开发环境，可以：

• ✅ 创建 ArkTS 项目
• ✅ 编译并生成 HAP
• ✅ 使用模拟器调试
• ✅ 真机运行与日志查看
• ✅ 使用 Preview 快速预览 UI
• ✅ 使用 HDC、Hvigor、OHPM 等工具完成日常开发