HarmonyOS APP＜＜古今职鉴定＞＞开源教程第2篇：开发环境搭建：DevEco Studio 全攻略

大雷神2026-05-12 8:23

本篇手把手教你安装配置 DevEco Studio，创建并运行第一个 HarmonyOS 项目

项目开源地址

https://gitcode.com/daleishen/gujinzhijian

学习目标

图：古今职鉴鸿蒙开发实战教程首页，开发环境搭建是进入项目实战的第一步。

完成本篇后，你将能够：

  • ✅ 成功安装 DevEco Studio 开发工具
  • ✅ 正确配置 HarmonyOS SDK
  • ✅ 创建并运行第一个 HarmonyOS 项目
  • ✅ 理解项目目录结构和配置文件

预计学习时间

约 60-90 分钟（包含下载和安装时间）

前置准备

  • 一台 Windows 10/11 或 macOS 10.15+ 的电脑
  • 至少 16GB 内存（推荐 32GB）
  • 至少 50GB 可用磁盘空间
  • 稳定的网络连接

第一部分：DevEco Studio 下载与安装

1.1 系统要求

在开始安装之前，请确认你的电脑满足以下要求：

Windows 系统要求：

项目 最低要求 推荐配置
操作系统 Windows 10 64位 Windows 11 64位
内存 8GB 16GB 或更高
硬盘 50GB 可用空间 SSD 100GB+
分辨率 1280×800 1920×1080 或更高

macOS 系统要求：

项目 最低要求 推荐配置
操作系统 macOS 10.15 macOS 12.0 或更高
芯片 Intel 或 Apple Silicon Apple Silicon (M1/M2/M3)
内存 8GB 16GB 或更高
硬盘 50GB 可用空间 SSD 100GB+

1.2 下载 DevEco Studio

步骤 1：访问华为开发者官网

打开浏览器，访问：https://developer.huawei.com/consumer/cn/deveco-studio/

步骤 2：选择版本下载

页面上会显示最新版本的 DevEco Studio，点击对应操作系统的下载按钮：

  • Windows 用户：下载 .exe 安装包
  • macOS 用户：下载 .dmg 安装包

💡 提示：建议下载最新稳定版本（如 DevEco Studio 6.0.x），不要下载 Beta 版本。

步骤 3：等待下载完成

安装包大小约 1-2GB，下载时间取决于网络速度。

1.3 安装 DevEco Studio

Windows 安装步骤

步骤 1：运行安装程序

双击下载的 .exe 文件，如果出现安全提示，点击"是"允许运行。

步骤 2：选择安装路径

复制代码 
默认路径：C:\Program Files\Huawei\DevEco Studio
推荐路径：D:\DevEco Studio（避免中文和空格）

⚠️ 注意：安装路径不要包含中文字符或空格，否则可能导致编译问题。

步骤 3：选择组件

勾选以下选项：

  • ✅ DevEco Studio
  • ✅ Create Desktop Shortcut（创建桌面快捷方式）
  • ✅ Add to PATH（添加到系统路径）

步骤 4：完成安装

点击"Install"开始安装，等待安装完成后点击"Finish"。

macOS 安装步骤

步骤 1：打开安装包

双击下载的 .dmg 文件，会弹出安装窗口。

步骤 2：拖拽安装

将 DevEco Studio 图标拖拽到 Applications 文件夹。

步骤 3：首次运行

打开 Applications 文件夹，右键点击 DevEco Studio，选择"打开"。

如果出现"无法验证开发者"的提示：

  1. 打开"系统偏好设置" → "安全性与隐私"
  2. 点击"仍要打开"

1.4 首次启动配置

步骤 1：启动 DevEco Studio

双击桌面快捷方式或从开始菜单启动。

步骤 2：导入设置

首次启动会询问是否导入之前的设置：

  • 如果是全新安装，选择"Do not import settings"
  • 如果是升级安装，可以选择导入之前的配置

步骤 3：同意许可协议

阅读并同意华为开发者协议和隐私政策。

步骤 4：登录华为账号

建议登录华为开发者账号，可以：

  • 同步设置和偏好
  • 使用远程模拟器
  • 访问更多开发资源

第二部分：SDK 配置与版本管理

2.1 SDK 自动下载

首次启动 DevEco Studio 后，会自动检测并提示下载 SDK。

步骤 1：进入 SDK 配置页面

如果没有自动弹出，可以通过以下路径进入：

  • Windows: File → Settings → SDK
  • macOS: DevEco Studio → Preferences → SDK

步骤 2：选择 SDK 安装路径

复制代码 
默认路径：
- Windows: C:\Users\<用户名>\AppData\Local\Huawei\Sdk
- macOS: /Users/<用户名>/Library/Huawei/Sdk

推荐路径：
- Windows: D:\HarmonyOS\Sdk
- macOS: /Users/<用户名>/HarmonyOS/Sdk

⚠️ 注意：SDK 路径同样不要包含中文字符或空格。

步骤 3：选择 API 版本

勾选需要安装的 API 版本：现在默认就安装好新新版本了 6.1对应的23

API 版本 对应系统版本 建议
API 20 HarmonyOS NEXT ✅ 必选（最新）
API 11 HarmonyOS 4.0 可选
API 10 HarmonyOS 3.1 可选

💡 建议：至少安装 API 20，这是 HarmonyOS NEXT 的 API 版本。

步骤 4：开始下载

点击"Apply"开始下载 SDK，下载大小约 5-10GB，请耐心等待。

2.2 SDK 组件说明（正确情况会自动安装）

SDK 包含以下主要组件：

组件 说明 大小
Toolchains 编译工具链 ~2GB
Previewer 预览器 ~500MB
System-image 模拟器系统镜像 ~3GB
Native 原生开发工具 ~1GB

2.3 检查 SDK 配置

安装完成后，验证 SDK 是否配置正确：

  1. 打开 File → Settings → SDK
  2. 确认 SDK 路径显示正确
  3. 确认 API 12 状态为"Installed"

第三部分：模拟器与真机调试配置

3.1 本地模拟器配置

DevEco Studio 提供了本地模拟器，可以在电脑上模拟鸿蒙设备。

步骤 1：打开设备管理器

点击工具栏的 Device Manager 图标，或通过菜单 Tools → Device Manager。

步骤 2：创建模拟器

  1. 点击 Create Device 按钮
  2. 选择设备类型：
  • Phone（手机）- 推荐首选
  • Tablet（平板）
  • Wearable（手表）
  • TV（电视）

步骤 3：配置模拟器参数

参数 推荐值 说明
Device Name MyPhone 自定义名称
System Image API 12 选择已安装的 API 版本
RAM 4096MB 内存大小
VM Heap 512MB 虚拟机堆大小

步骤 4：启动模拟器

创建完成后，点击模拟器旁边的 ▶️ 按钮启动。

首次启动需要较长时间（1-3分钟），请耐心等待。

3.2 远程模拟器（推荐）

如果电脑配置较低，可以使用华为提供的远程模拟器。

优势：

  • 不占用本地资源
  • 启动速度快
  • 支持更多设备类型

使用步骤：

  1. 确保已登录华为开发者账号
  2. 在 Device Manager 中选择 Remote Device
  3. 选择需要的设备类型
  4. 点击连接

⚠️ 注意：远程模拟器有使用时长限制，每天约 2-4 小时。

3.3 真机调试配置

使用真机调试可以获得最真实的运行效果。

步骤 1：开启开发者模式

在鸿蒙设备上：

  1. 打开 设置 → 关于手机
  2. 连续点击 版本号 7次
  3. 返回设置，进入 开发者选项
  4. 开启 USB 调试

步骤 2：连接设备

  1. 使用 USB 数据线连接手机和电脑
  2. 手机上会弹出授权提示，点击"允许"
  3. DevEco Studio 会自动识别设备

步骤 3：验证连接

在 Device Manager 中应该能看到你的设备，状态显示为"Online"。

常见问题排查：

问题 解决方案
设备未识别 重启编辑器或者查看数据线是否为原装线
授权失败 重新插拔 USB，重新授权
连接不稳定 更换 USB 线或 USB 端口

第四部分：创建第一个 HarmonyOS 项目

4.1 创建新项目

步骤 1：打开创建向导

启动 DevEco Studio 后，点击 Create Project。

或者通过菜单：File → New → Create Project

步骤 2：选择项目模板

在模板列表中选择：

  • Application → Empty Ability

这是最基础的项目模板，适合学习使用。

步骤 3：配置项目信息

配置项 示例值 说明
Project name MyFirstApp 项目名称（英文）
Bundle name com.example.myfirstapp 应用包名
Save location D:\Projects\MyFirstApp 项目保存路径
Compile SDK 20 编译 SDK 版本
Model Stage（现在不用选择了） 应用模型（选 Stage）
Language ArkTS 开发语言

⚠️ 重要 ： - 项目名称和路径不要包含中文 - Model 必须选择 Stage（FA 模型已废弃） - Language 选择 ArkTS

步骤 4：完成创建

点击 Finish，等待项目创建和依赖下载完成。

首次创建项目需要下载依赖，可能需要几分钟时间。

4.2 项目结构解析

创建完成后，项目结构如下：

复制代码 
MyFirstApp/
├── .hvigor/                    # 构建缓存目录
├── AppScope/                   # 应用级配置
│   ├── app.json5               # 应用配置文件
│   └── resources/              # 应用级资源
│       └── base/
│           ├── element/        # 字符串等元素
│           └── media/          # 图片资源
├── entry/                      # 入口模块（主模块）
│   ├── src/
│   │   └── main/
│   │       ├── ets/            # ArkTS 源代码
│   │       │   ├── entryability/
│   │       │   │   └── EntryAbility.ets  # 应用入口
│   │       │   └── pages/
│   │       │       └── Index.ets         # 首页
│   │       ├── resources/      # 模块资源
│   │       └── module.json5    # 模块配置
│   ├── build-profile.json5     # 构建配置
│   └── oh-package.json5        # 依赖配置
├── build-profile.json5         # 项目构建配置
├── hvigorfile.ts               # 构建脚本
└── oh-package.json5            # 项目依赖配置

4.3 核心配置文件详解

app.json5 - 应用配置
json5 复制代码 
{
  "app": {
    "bundleName": "com.example.myfirstapp",  // 应用包名，全局唯一
    "vendor": "example",                      // 开发者/公司名称
    "versionCode": 1000000,                   // 版本号（整数）
    "versionName": "1.0.0",                   // 版本名称（显示给用户）
    "icon": "$media:app_icon",                // 应用图标
    "label": "$string:app_name"               // 应用名称
  }
}
module.json5 - 模块配置
json5 复制代码 
{
  "module": {
    "name": "entry",                          // 模块名称
    "type": "entry",                          // 模块类型：entry/feature/har
    "description": "$string:module_desc",     // 模块描述
    "mainElement": "EntryAbility",            // 入口 Ability
    "deviceTypes": [                          // 支持的设备类型
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,              // 是否随应用安装
    "installationFree": false,                // 是否支持免安装
    "pages": "$profile:main_pages",           // 页面配置文件
    "abilities": [                            // Ability 列表
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}
oh-package.json5 - 依赖配置
json5 复制代码 
{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    // 项目依赖在这里添加
  }
}

4.4 理解入口文件

EntryAbility.ets - 应用入口
typescript 复制代码 
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  // 应用创建时调用
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
  }

  // 应用销毁时调用
  onDestroy(): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  // 窗口创建时调用
  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

    // 加载首页
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
    });
  }

  // 窗口销毁时调用
  onWindowStageDestroy(): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  // 应用进入前台
  onForeground(): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
  }

  // 应用进入后台
  onBackground(): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
  }
}
Index.ets - 首页
typescript 复制代码 
@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

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

第五部分：运行第一个应用

5.1 选择运行设备

在工具栏的设备选择下拉框中，选择：

  • 本地模拟器（如果已创建）
  • 远程模拟器
  • 真机（如果已连接）

5.2 运行应用

方法一：点击运行按钮

点击工具栏的 ▶️ 按钮。

方法二：使用快捷键

  • Windows: Shift + F10
  • macOS: Control + R

方法三：使用菜单

Run → Run 'entry'

5.3 查看运行结果

如果一切正常，你应该能看到：

复制代码 
┌─────────────────────────────────────────┐
│                                          │
│                                          │
│                                          │
│            Hello World                   │
│                                          │
│                                          │
│                                          │
└─────────────────────────────────────────┘

🎉 恭喜！你已经成功运行了第一个 HarmonyOS 应用！

5.4 修改代码并热重载

现在让我们修改代码，体验热重载功能：

步骤 1：修改 Index.ets

将 message 的值改为中文：

typescript 复制代码 
@State message: string = '你好，鸿蒙！';

步骤 2：保存文件

按 Ctrl + S（Windows）或 Cmd + S（macOS）保存。

步骤 3：查看效果

如果开启了热重载，界面会自动更新显示"你好，鸿蒙！"。

如果没有自动更新，点击工具栏的 🔄 按钮手动刷新。

第六部分：构建与调试

6.1 构建项目

使用命令行构建：

打开终端（Terminal），在项目根目录执行：

bash 复制代码 
hvigorw assembleHap --no-daemon

构建输出：

构建成功后，HAP 包位于：

复制代码 
entry/build/default/outputs/default/entry-default-signed.hap

6.2 查看构建日志

构建过程中的日志会显示在 DevEco Studio 底部的 Build 面板中。

常见构建错误：

错误信息 原因 解决方案
SDK not found SDK 未配置 检查 SDK 路径设置
Compile error 代码语法错误 查看错误详情，修复代码
Resource not found 资源文件缺失 检查资源文件是否存在

6.3 调试技巧

1. 使用 console.log 输出日志

typescript 复制代码 
console.log('调试信息');
console.info('信息');
console.warn('警告');
console.error('错误');

2. 使用 hilog 输出日志

typescript 复制代码 
import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'MyTag', '这是一条日志');

3. 查看日志

在 DevEco Studio 底部的 Log 面板中查看日志输出。

4. 设置断点

在代码行号左侧点击，设置断点。运行调试模式（🐛 按钮）时，程序会在断点处暂停。

第七部分：常见问题排查

7.1 安装问题

问题 解决方案
安装包损坏 重新下载安装包
安装路径有中文 选择纯英文路径重新安装
权限不足 以管理员身份运行安装程序

7.2 SDK 问题

问题 解决方案
SDK 下载失败 检查网络连接，使用代理
SDK 路径无效 选择有写入权限的路径
API 版本不匹配 下载对应版本的 SDK

7.3 模拟器问题

问题 解决方案
模拟器启动慢 增加内存配置，使用 SSD
模拟器黑屏 重启模拟器，检查显卡驱动
模拟器闪退 检查 Hyper-V 是否开启

7.4 构建问题

问题 解决方案
构建失败 查看错误日志，修复代码
依赖下载失败 检查网络，清理缓存重试
签名错误 检查签名配置

本篇小结

完成的任务

任务 状态
安装 DevEco Studio ✅
配置 HarmonyOS SDK ✅
创建模拟器 ✅
创建第一个项目 ✅
运行应用 ✅
理解项目结构 ✅

关键文件速查

文件 作用
app.json5 应用级配置（包名、版本等）
module.json5 模块配置（Ability、权限等）
oh-package.json5 依赖管理
EntryAbility.ets 应用入口
Index.ets 首页

常用快捷键

功能 Windows macOS
运行 Shift + F10 Control + R
调试 Shift + F9 Control + D
保存 Ctrl + S Cmd + S
格式化 Ctrl + Alt + L Cmd + Option + L

下一篇预告

第3篇 ArkTS 语言基础：TypeScript 的鸿蒙进化

下一篇我们将学习：

  • ArkTS 与 TypeScript 的区别
  • 变量、函数、接口、枚举的定义
  • ArkTS 的特殊限制规则
  • 为项目创建官职数据模型

参考资料

*本教程基于「古今职鉴」真实项目编写，所有代码均经过实际验证。快下载源代码跑起来把*

相关推荐
Swift社区1 小时前
鸿蒙 PC 多窗口系统：一次讲透实现原理
华为·harmonyos
xmdy58661 小时前
Flutter + 开源鸿蒙实战｜城市智慧停车管理系统 Day3 车场详情+车位预约+计时计费算法+路线导航+常用车场缓存持久化
flutter·开源·harmonyos
xmdy58661 小时前
Flutter+开源鸿蒙实战｜城市共享驿站智能存取系统 Day6 全局UI精细化美化+通用组件封装+反馈设置模块+隐私弹窗+鸿蒙打包签名适配+项目整体重构
flutter·开源·harmonyos
三声三视1 小时前
Electron+鸿蒙桌面应用实战：跨平台开发完全指南
electron·harmonyos·鸿蒙·桌面
求学中--1 小时前
鸿蒙实战：用状态管理实现一个完整的Todo应用，从@State到@Provide全链路打通
华为·harmonyos·组件化开发·完整项目
容器魔方1 小时前
Karmada 用户组再迎新成员 | GMI Cloud 正式加入！
大数据·云原生·容器·华为云·云计算
HwJack2010 小时前
HarmonyOS APP开发玩转鸿蒙 HSP：打造高复用“乐高模块”的底层逻辑
华为·harmonyos
●VON17 小时前
28个Token重构鸿蒙App：企业级设计系统的搭建实践
华为·重构·harmonyos
求学中--19 小时前
AppStorage和LocalStorage有什么区别？鸿蒙全局状态管理方案选型指南
华为·harmonyos
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03【AI】2026 年具身智能模型和世界模型总结04CC-Switch & Claude 基于 Linux 服务器安装使用指南05零基础教你claude code 接入 deepseek V406Windows端Codex接入第三方模型（DeekSeek，BaiLian)07要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法082026年AI前瞻：量子AI、具身智能与科学发现的新纪元09裂开！ChatGPT 居然开始要手机号验证，附详细解决方法10Cursor 接入 DeepSeek‑V4‑Pro 完整指南（2026 实测）