从零搭建完整 HarmonyOS 应用实战教程

本文将带你从零开始搭建一个完整的 HarmonyOS 应用。我们以 MoodLite（心情日记）为实战案例，手把手讲解项目初始化、模块结构、配置文件、入口页面等核心环节，让你快速上手鸿蒙开发。

一、开发环境准备

1.1 安装 DevEco Studio

DevEco Studio 是华为官方提供的 HarmonyOS 集成开发环境，基于 IntelliJ IDEA 构建。前往华为开发者官网下载最新版本。

推荐使用 DevEco Studio 5.0+ 版本，内置 HarmonyOS SDK 6.0，支持最新的 ArkTS 语法特性。

1.2 配置 SDK

安装完成后，进入 File → Settings → HarmonyOS SDK，确保已下载以下组件：

组件	说明	是否必须
HarmonyOS SDK	核心开发包	✅ 必须
Toolchains	编译与构建工具	✅ 必须
Previewer	UI 预览器	推荐
SysCap	系统能力集	可选

二、创建项目

2.1 新建工程

打开 DevEco Studio，选择 Create HarmonyOS Project，模板选择 Empty Ability。填写项目信息：

配置项	示例值	说明
Project Name	MoodLite	项目名称
Bundle Name	com.example.moodlite	应用包名（唯一标识）
Compile SDK	6.0.1(21)	编译 SDK 版本
Module Name	entry	主模块名称
Language	ArkTS	开发语言

2.2 项目目录结构

复制代码

MoodLite/
├── AppScope/                    # 应用级配置
│   ├── app.json5                # 应用配置（包名、版本等）
│   └── resources/               # 应用级资源（图标等）
├── entry/                       # 主模块
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/             # ArkTS 源代码
│   │   │   │   ├── pages/       # 页面
│   │   │   │   ├── model/       # 数据模型
│   │   │   │   ├── viewmodel/   # 视图模型
│   │   │   │   ├── data/        # 数据层
│   │   │   │   ├── common/      # 公共模块
│   │   │   │   └── widget/      # 桌面小组件
│   │   │   ├── resources/       # 模块资源
│   │   │   └── module.json5     # 模块配置
│   │   ├── mock/                # Mock 数据
│   │   ├── ohosTest/            # 鸿蒙测试
│   │   └── test/                # 单元测试
│   ├── build-profile.json5      # 模块构建配置
│   └── oh-package.json5         # 模块依赖
├── build-profile.json5          # 项目构建配置
├── oh-package.json5             # 项目依赖
└── hvigorfile.ts                # 构建脚本

三、核心配置文件详解

3.1 应用配置 --- app.json5

json5 复制代码

{
  "app": {
    "bundleName": "com.example.moodlite",
    "vendor": "MoodLite",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

3.2 模块配置 --- module.json5

json5 复制代码

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages"
  }
}

3.3 构建配置 --- build-profile.json5

json5 复制代码

{
  "app": {
    "products": [{
      "name": "default",
      "targetSdkVersion": "6.0.1(21)",
      "compatibleSdkVersion": "6.0.1(21)",
      "runtimeOS": "HarmonyOS"
    }]
  },
  "modules": [{
    "name": "entry",
    "srcPath": "./entry"
  }]
}

四、编写第一个页面

4.1 入口能力 --- EntryAbility

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, "MoodLite", "Ability onCreate");
  }

  onDestroy(): void {
    hilog.info(0x0000, "MoodLite", "Ability onDestroy");
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0000, "MoodLite", "Ability onWindowStageCreate");
    windowStage.loadContent("pages/MainPage", (err) => {
      if (err.code) {
        hilog.error(0x0000, "MoodLite", "Failed to load content: %{public}s", JSON.stringify(err));
        return;
      }
      hilog.info(0x0000, "MoodLite", "Succeeded in loading content");
    });
  }
}

4.2 主页面 --- MainPage

ets 复制代码

@Entry
@Component
struct MainPage {
  @State message: string = "Hello MoodLite";

  build() {
    Column() {
      Text(this.message)
        .fontSize(32)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      Button("开始记录心情")
        .fontSize(18)
        .width("60%")
        .height(50)
        .onClick(() => {
          this.message = "欢迎使用 MoodLite!";
        })
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

4.3 注册页面路由

json5 复制代码

{
  "src": [
    "pages/MainPage",
    "pages/Welcome",
    "pages/AddEntry"
  ]
}

五、运行与调试

5.1 模拟器运行

DevEco Studio 内置 HarmonyOS 模拟器，点击工具栏的 Run 按钮即可启动。

5.2 真机调试

连接鸿蒙手机后，在 File → Project Structure → Signing Configs 中配置签名证书，即可部署到真机。

真机调试必须配置签名。开发阶段可使用自动签名，上架时需替换为正式证书。

总结

本文以 MoodLite 心情日记为案例，简要讲解了从零搭建鸿蒙应用的核心流程，包括开发环境准备、项目创建、核心配置文件解析、页面编写及运行调试，覆盖鸿蒙开发入门关键要点，帮助快速上手 ArkTS 及 HarmonyOS 应用开发。