HarmonyOS 6.0 开发环境搭建完全指南 - DevEco Studio 配置 + 真机调试实战

记录疯狂～

212人浏览 · 2026-02-03 13:19:11

记录疯狂～ · 2026-02-03 13:19:11 发布

系列文章：HarmonyOS 6.0 实战开发 - 「今天空白」应用 第2篇 / 共30篇 发布时间：2026-02-03 阅读时长：15分钟难度：（入门）

本文导读

欢迎来到系列第2篇！

在上一篇中，我们了解了「今天空白」应用的产品理念和技术栈。从今天开始，我们正式进入实战阶段。

本文内容：

DevEco Studio 5.0.3+ 下载与安装
HarmonyOS 6.0 SDK 配置
签名证书申请（自动签名 + 手动签名）
创建第一个 HarmonyOS 6.0 应用
真机调试完整流程
常见问题排查

学完本文你将：

搭建好完整的 HarmonyOS 6.0 开发环境
成功运行第一个应用
掌握真机调试技巧

系统要求

硬件要求

项目	最低要求	推荐配置
CPU	Intel i5 / AMD Ryzen 5	Intel i7 / AMD Ryzen 7
内存	8GB	16GB 及以上
硬盘	20GB 可用空间	SSD 50GB 可用空间

操作系统

macOS：10.15 (Catalina) 及以上 Windows：Windows 10 64位及以上 Linux：暂不支持（截至2026年1月）

网络要求

需要稳定的网络连接（下载 SDK 约 2-3GB）
建议使用有线网络或稳定的 Wi-Fi

第一步：下载 DevEco Studio

1.1 访问官方下载页

打开浏览器，访问华为开发者官网：

https://developer.harmonyos.com/cn/develop/deveco-studio

1.2 选择版本

找到 DevEco Studio 5.0.3.900 或更高版本（支持 HarmonyOS 6.0）

重要：必须使用 5.0.3.900+ 版本才支持 HarmonyOS 6.0 (API 20)

根据你的操作系统选择：

macOS：deveco-studio-5.0.3.900-mac-arm.dmg（Apple Silicon）
macOS：deveco-studio-5.0.3.900-mac-x64.dmg（Intel）
Windows：deveco-studio-5.0.3.900-windows-x64.exe

1.3 下载并安装

macOS 安装步骤：

双击 .dmg 文件
将 DevEco Studio 拖拽到 Applications 文件夹
首次打开可能提示"无法验证开发者"
- 前往"系统偏好设置" → "安全性与隐私"
- 点击"仍要打开"

Windows 安装步骤：

双击 .exe 文件
选择安装路径（建议默认）
勾选"创建桌面快捷方式"
完成安装

第二步：首次启动配置

2.1 启动 DevEco Studio

第一次启动会进入配置向导。

2.2 选择 UI 主题

选择你喜欢的主题：

Darcula（暗黑主题，推荐）
Light（浅色主题）

2.3 安装 Node.js

DevEco Studio 会检测 Node.js：

如果未安装：

勾选"Install Node.js"
DevEco Studio 会自动安装 Node.js

如果已安装：

确保版本 >= 18.0.0（推荐使用 v20+ 或 v24+ LTS 版本）
查看版本：node -v

2.4 配置 SDK

关键步骤！

选择 SDK 位置

macOS 默认：~/Library/Huawei/Sdk
Windows 默认：C:\Users\你的用户名\AppData\Local\Huawei\Sdk

建议使用默认路径。

选择 API 版本
- 勾选 API 20 (HarmonyOS 6.0.0.47)
- 同时勾选 API 12（兼容性考虑）
点击 Next 开始下载 SDK（约 2-3GB，需要时间）

2.5 同意协议

阅读并同意许可协议。

2.6 完成配置

点击 Finish，进入 DevEco Studio 主界面。

第三步：创建第一个项目

3.1 创建新项目

点击 Create Project

3.2 选择模板

选择：Application → Empty Ability

点击 Next

3.3 配置项目信息

填写以下信息：

配置项	值	说明
Project name	`TodayBlank`	项目名称
Bundle name	`com.zq.today_is_blank`	应用包名（必须唯一）
Save location	自定义	项目保存路径
Compile SDK	`API 20`	编译 SDK 版本
Compatible SDK	`API 20`	兼容的最低版本
Device type	`Phone`	设备类型
Language	`ArkTS`	开发语言

注意：Bundle name 必须全局唯一，建议使用你自己的域名倒序。

3.4 点击 Finish

DevEco Studio 会自动：

创建项目结构
下载依赖（Hvigor）
初始化 Git 仓库

等待项目创建完成（首次可能需要几分钟）。

项目结构解析

创建完成后，你会看到这样的目录结构：

TodayBlank/
├── AppScope/                 # 应用全局配置
│   └── resources/
│       └── base/
│           └── element/
│               └── string.json    # 全局字符串资源
├── entry/                    # 主模块
│   ├── src/
│   │   └── main/
│   │       ├── ets/          # ArkTS 源码
│   │       │   ├── entryability/
│   │       │   │   └── EntryAbility.ets  # 应用入口
│   │       │   └── pages/
│   │       │       └── Index.ets         # 首页
│   │       ├── resources/    # 资源文件
│   │       └── module.json5  # 模块配置
│   └── build-profile.json5   # 构建配置
├── hvigor/                   # 构建工具
├── oh-package.json5          # 依赖管理
├── build-profile.json5       # 全局构建配置
└── hvigorfile.ts            # 构建脚本

关键文件说明

build-profile.json5（全局构建配置）

{
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": "6.0.0(20)",      // 目标 SDK
        "compatibleSdkVersion": "6.0.0(20)",  // 兼容 SDK
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

entry/src/main/ets/pages/Index.ets（首页代码）

@Entry
@ComponentV2
struct Index {
  @Local message: string = 'Hello HarmonyOS 6.0';

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

第四步：配置签名证书

要在真机上运行应用，必须配置签名证书。

方式一：自动签名（推荐）

4.1 登录华为账号

点击菜单：File → Settings（macOS 为 DevEco Studio → Settings）
找到：Build, Execution, Deployment → Debugger
勾选 Sign in
输入华为账号并登录

4.2 配置自动签名

点击菜单：File → Project Structure
选择 Project → Signing Configs
勾选 Automatically generate signature
选择 Support HarmonyOS
点击 OK

DevEco Studio 会自动：

创建证书
生成 Provisioning Profile
配置签名

方式二：手动签名

如果自动签名失败，可以手动配置。

4.3 申请证书

访问：https://developer.huawei.com/consumer/cn/
登录华为开发者账号
进入"证书管理"
创建新证书（选择"调试证书"）
下载 .p12 证书文件

4.4 创建 Profile

在证书管理页面，创建"Provisioning Profile"
选择"调试"类型
选择刚才创建的证书
添加测试设备（需要设备 UDID）
下载 .p7b 文件

4.5 配置到项目

打开 File → Project Structure → Signing Configs
取消勾选"Automatically generate signature"
手动选择：
- Signing certificate：.p12 文件
- Profile：.p7b 文件
- Password：证书密码
点击 OK

第五步：真机调试

5.1 准备真机

开启开发者模式：

打开手机"设置"
进入"关于手机"
连续点击"版本号" 7 次
返回"设置"，会出现"开发者选项"

开启 USB 调试：

进入"开发者选项"
开启"USB 调试"
开启"USB 调试(安全设置)"（如果有）

连接电脑：

使用 USB 数据线连接手机和电脑
手机会弹出"允许 USB 调试"提示，点击"允许"

5.2 检测设备

在 DevEco Studio 底部，找到设备选择器：

如果看到你的设备名称（如"HUAWEI Mate 60"），说明连接成功。

如果没有显示设备：

检查 USB 线是否连接稳定
重新开启 USB 调试
使用命令检测：
```
hdc list targets
```
应该能看到设备 ID。

5.3 运行应用

点击工具栏的 Run 按钮（绿色三角形），或按快捷键：

macOS：Ctrl + R
Windows：Shift + F10

首次运行：

DevEco Studio 会编译项目
自动安装 HAP 到手机
启动应用

成功标志：

手机屏幕显示"Hello HarmonyOS 6.0"
DevEco Studio 控制台显示"Launch ability succeed"

常见问题与解决

问题 1：SDK 下载失败

现象：SDK Manager 一直显示"Downloading..."

解决方案：

检查网络连接
关闭代理或 VPN
手动下载 SDK：
- 访问官网下载 SDK 压缩包
- 解压到 SDK 目录

问题 2：设备未识别

现象：设备列表为空

解决方案：

# 1. 检查 hdc 是否正常
hdc version

# 2. 查看设备列表
hdc list targets

# 3. 如果为空，重启 hdc 服务
hdc kill
hdc start

# 4. 再次查看
hdc list targets

问题 3：签名失败

现象：Error: Signing failed

解决方案：

检查证书是否过期
检查 Bundle name 是否与证书匹配
重新生成自动签名
使用手动签名并检查密码

问题 4：编译失败

现象：Build failed with errors

解决方案：

# 1. 清理缓存
Build → Clean Project

# 2. 重新构建
Build → Rebuild Project

# 3. 检查 Node.js 版本
node -v  # 应该 >= 18.0.0 (推荐 v20+ 或 v24+)

# 4. 清理 Hvigor 缓存
rm -rf .hvigor

问题 5：应用闪退

现象：应用安装后立即闪退

解决方案：

查看 HiLog 日志：
```
hdc shell hilog -x
```
检查权限配置（module.json5）
检查代码是否有运行时错误

验证环境搭建成功

运行以下命令，确保环境正常：

# 1. 检查 DevEco Studio 版本
# 菜单：DevEco Studio → About DevEco Studio
# 应该显示：5.0.3.900 或更高

# 2. 检查 SDK 版本
# Settings → SDK → SDK Platforms
# 应该看到：API 20 (6.0.0.47) 已安装

# 3. 检查 hdc 命令
hdc version
# 输出：Ver: 2.0.0

# 4. 检查设备连接
hdc list targets
# 输出：设备 ID（如果连接了真机）

# 5. 检查 Node.js
node -v
# 输出：v20.x.x 或 v24.x.x（推荐使用最新 LTS 版本）

全部通过，说明环境搭建成功！

第一个任务：修改 Hello World

现在，让我们修改代码，体验一下 ArkTS 开发。

任务 1：修改文本

打开 entry/src/main/ets/pages/Index.ets：

@Entry
@ComponentV2
struct Index {
  @Local message: string = '今天空白';  // 修改这里

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .fontColor('#1A1A1A')  // 添加颜色
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#F5F5F5')  // 添加背景色
  }
}

保存文件，应用会热重载，手机屏幕立即显示"今天空白"。

任务 2：添加按钮

继续修改：

@Entry
@ComponentV2
struct Index {
  @Local message: string = '今天空白';
  @Local count: number = 0;

  build() {
    Column({ space: 20 }) {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .fontColor('#1A1A1A')

      Text(`点击次数：${this.count}`)
        .fontSize(20)
        .fontColor('#666666')

      Button('点击我')
        .onClick(() => {
          this.count++;
        })
        .height(44)
        .width(200)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#F5F5F5')
  }
}

保存后，点击按钮，计数会增加。

恭喜！你已经完成了第一个交互式应用！

学习检查清单

完成本文后，你应该能够：

成功安装 DevEco Studio 5.0.3+
下载并配置 HarmonyOS 6.0 SDK (API 20)
创建第一个 HarmonyOS 项目
配置签名证书（自动或手动）
连接真机并成功运行应用
理解项目基本结构
修改代码并看到效果

扩展学习

hdc 常用命令

# 查看设备列表
hdc list targets

# 安装 HAP
hdc install entry-default-signed.hap

# 卸载应用
hdc uninstall com.zq.today_is_blank

# 启动应用
hdc shell aa start -a EntryAbility -b com.zq.today_is_blank

# 查看日志
hdc shell hilog

# 清空日志
hdc shell hilog -r

# 截屏
hdc shell snapshot_display -f /data/screen.png
hdc file recv /data/screen.png ./screen.png

# 文件传输
hdc file send local.txt /data/local/tmp/
hdc file recv /data/local/tmp/remote.txt ./