鸿蒙原生项目实战（一）：项目初始化与工程架构解析

本系列基于 HarmonyOS NEXT 6.1.1（API 23）平台，以一款名为「习惯大师」的完整应用为实例，从零到一带你掌握鸿蒙原生开发全流程。

---

一、前言

在正式开始编码前，我们需要先搭建好鸿蒙原生开发环境。本文默认你已经完成了以下准备工作：

• 安装了 DevEco Studio NEXT（推荐 5.0+ 版本）
• 配置了 HarmonyOS SDK（本文基于 API 23/24，即 HarmonyOS 6.1.x）
• 注册了华为开发者账号并完成了签名配置

---

二、创建项目

2.1 新建项目

打开 DevEco Studio，点击 Create Project：

1. 选择 Empty Ability 模板
2. 填写项目名称：MyApplication
3. Bundle name：com.example.myapplication
4. Compatible SDK：6.1.0(23)
5. 语言：ArkTS

2.2 项目结构概览

创建完成后，我们来看项目的整体目录结构：

MyApplication/
├── AppScope/                    # 应用级配置与资源
│   ├── app.json5               # 全局应用配置
│   └── resources/              # 应用级资源（图标、字符串）
├── entry/                       # 主模块（entry类型）
│   ├── src/main/ets/           # ArkTS源码目录
│   │   ├── entryability/       # Ability生命周期
│   │   ├── entrybackupability/ # 备份扩展能力
│   │   ├── model/              # 数据模型与业务逻辑
│   │   └── pages/              # 页面组件
│   ├── src/main/resources/     # 模块级资源
│   └── build-profile.json5     # 模块构建配置
├── hvigor/                     # 构建工具配置
├── oh_modules/                 # 依赖模块
├── build-profile.json5         # 应用级构建配置
├── hvigorfile.ts              # 构建入口脚本
└── oh-package.json5           # 包管理配置

---

三、核心配置解析

3.1 应用级配置：AppScope/app.json5

{
  "app": {
    "bundleName": "com.example.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "buildVersion": "1",
    "icon": "$media:layered_image",
    "label": "$string:app_name"
  }
}

关键字段说明：

字段	说明	注意点
bundleName	应用唯一标识	发布后不可更改
versionCode	内部版本号	递增的正整数
versionName	用户可见版本	语义化版本号
icon	应用图标	使用 $media: 资源引用
label	应用名称	使用 $string: 资源引用

3.2 模块级配置：entry/build-profile.json5

{
  "apiType": "stageMode",
  "buildOption": {
    "strictMode": {
      "caseSensitiveCheck": true,
      "useNormalizedOHMUrl": true
    }
  }
}

这里启用了大小写敏感检查和规范化 OHM URL，这是 HarmonyOS 6.1 后的推荐实践。

3.3 模块声明：module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["ohos.want.action.home"]
          }
        ]
      }
    ],
    "extensionAbilities": [
      {
        "name": "EntryBackupAbility",
        "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
        "type": "backup",
        "exported": false
      }
    ]
  }
}

重点理解：

• type: "entry"：标识这是主入口模块，一个应用只有一个
• skills：配置系统意图（Want）过滤，entity.system.home + ohos.want.action.home 表示这是一个桌面启动应用
• extensionAbilities：扩展能力，这里注册了一个备份恢复扩展

3.4 页面路由配置

resources/base/profile/main_pages.json：

{
  "src": [
    "pages/Index",
    "pages/AddHabit",
    "pages/HabitDetail",
    "pages/Statistics",
    "pages/Settings"
  ]
}

所有页面必须在此注册，这是 ArkTS 路由系统的要求。我们的「习惯大师」共有 5 个页面：

页面	功能
Index	首页：今日进度 + 习惯列表 + 打卡
AddHabit	添加新习惯
HabitDetail	习惯详情 + 日历视图
Statistics	统计分析 + 趋势图
Settings	设置与数据管理

---

四、构建配置体系

4.1 应用级 build-profile.json5

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "6.1.1(24)",
        "compatibleSdkVersion": "6.1.0(23)",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [{ "name": "default", "applyToProducts": ["default"] }]
    }
  ]
}

4.2 Hvigor 构建配置

{
  "modelVersion": "6.1.1",
  "execution": {
    "daemon": true,        // 启用守护进程编译
    "incremental": true,   // 增量编译
    "parallel": true,      // 并行编译
    "typeCheck": false     // 关闭类型检查（加快构建）
  }
}

⚠️ 开发阶段建议 typeCheck: false 以加速热重载，发布前再开启。

---

五、资源管理机制

5.1 color 资源

{
  "color": [
    { "name": "primary",       "value": "#6C5CE7" },
    { "name": "primary_dark",  "value": "#5A4BD1" },
    { "name": "bg_page",       "value": "#F0F4F8" },
    { "name": "card_bg",       "value": "#FFFFFF" },
    { "name": "text_primary",  "value": "#2D3436" },
    { "name": "text_secondary","value": "#636E72" },
    { "name": "completed",     "value": "#00B894" },
    { "name": "incomplete",    "value": "#DFE6E9" }
  ]
}

通过 $r('app.color.primary') 引用，方便全局统一换肤。

5.2 深色主题适配

resources/dark/element/color.json：

{
  "color": [
    { "name": "start_window_background", "value": "#000000" }
  ]
}

鸿蒙原生支持自动匹配深色模式资源，无需代码判断。只需在 dark/ 目录下定义同名资源即可覆盖。

---

六、Ability 生命周期

EntryAbility.ets：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { HabitManager } from '../model/DataManager';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    HabitManager.init(this.context);  // 初始化数据管理器
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed: %{public}s', JSON.stringify(err));
      }
    });
  }
}

生命周期要点：

• onCreate：应用启动时调用，在此完成全局初始化（如数据管理器）
• onWindowStageCreate：窗口创建后加载首屏页面
• onForeground / onBackground：前后台切换回调

---

七、实践要点总结

1. 命名规范：$r() 资源引用是 ArkTS 推荐的国际化/主题化方案，硬编码颜色值应尽量避免
2. module.json5 中的 skills：要启动应用必须配置 entity.system.home + ohos.want.action.home
3. 页面注册：新增页面后必须在 main_pages.json 注册，否则路由会失败
4. 增量编译：Hvigor 默认启用增量编译，首次构建较慢，后续热重载极快
   

---

八、下篇预告

下一篇我们将深入数据模型与持久化层设计，内容包括：

• ArkTS 枚举与接口定义
• Preferences 轻量级数据库的使用
• Manager 单例模式设计
• 复杂数据结构的序列化/反序列化

👉 下一篇：数据模型与持久化层设计

---

本文所有代码片段均来自真实鸿蒙 NEXT 项目「习惯大师」，你可以对照源码阅读效果更佳。