【鸿蒙原生开发实战】第一篇：环境搭建与项目初始化——从零开始搭建「知墨」笔记应用

前言

HarmonyOS NEXT（鸿蒙原生）正式面向开发者开放以来，越来越多的团队开始拥抱纯血鸿蒙生态。作为一个从 Android 转过来的开发者，我决定用 ArkTS + ArkUI 开发一个完整的笔记应用——「知墨」（KnowInk），以实战的方式记录鸿蒙原生开发的全流程。

本篇是系列的第一篇，我们会从开发环境搭建开始，一步步创建项目、理解工程结构、完成首次构建。

---

一、开发环境准备

1.1 安装 DevEco Studio

鸿蒙官方的 IDE 是 DevEco Studio，基于 IntelliJ IDEA 社区版定制。可以在华为开发者官网下载最新版本。

当前版本：DevEco Studio 6.1 （对应 HarmonyOS SDK 6.1.0）

安装过程比较常规，需要注意的是：

• 安装路径不要有中文和空格（虽然官方说支持，但为了省心，建议用英文路径）
• 安装完成后会自动拉起 SDK 下载向导，建议勾选 HarmonyOS SDK 6.x 全量下载
• node.js 已经内置于 DevEco Studio 中，无需单独安装

1.2 配置 SDK 环境变量

安装完成后，需要配置 DEVECO_SDK_HOME 环境变量，指向 SDK 目录。我的安装路径是：

D:\DevEco Studio

SDK 默认安装在 D:\DevEco Studio\sdk，因此环境变量配置为：

变量名：DEVECO_SDK_HOME
变量值：D:\DevEco Studio\sdk

SDK 目录结构如下：

sdk/
└── default/
    ├── hms/               # 华为移动服务 SDK
    │   ├── ets/           # ArkTS 声明式开发套件
    │   ├── js/            # 兼容 JS 开发套件
    │   ├── native/        # C++ 原生开发套件
    │   └── toolchains/    # 构建工具链
    └── openharmony/       # 开源鸿蒙 SDK
        ├── ets/
        ├── js/
        ├── native/
        └── toolchains/

踩坑记录：首次执行 hvigorw --sync 时遇到如下错误：

> hvigor ERROR: 00303217 Configuration Error
Error Message: Invalid value of 'DEVECO_SDK_HOME' in the system environment path.

这是因为 hvigor daemon 进程启动时缓存了环境变量状态。解决方案很简单——先停止 daemon，再重新执行：

cd 项目根目录
"D:\DevEco Studio\tools\node\node.exe" "D:\DevEco Studio\tools\hvigor\bin\hvigorw.js" --stop-daemon

然后再执行 --sync 就正常了。

---

二、创建 HarmonyOS 项目

2.1 新建项目

打开 DevEco Studio，点击 Create New Project：

（插入截图：新建项目向导第一步）

选择模板时需要注意：

模板类型	适用场景
Empty Ability	空白模板，适合从零开始
List	列表类应用模板
Tab	底部 Tab 导航模板
Login	登录页面模板

我选择了 Empty Ability（Stage Model），因为我们要从零构建自定义 UI。

（插入截图：选择模板页面）

2.2 项目配置

填写项目信息：

• Project Name: MyApplication（后续可改为 knowink）
• Bundle Name: com.example.myapplication（发布前改为自己的包名）
• Save Location: D:\harmonyos\project\6.5\3\MyApplication
• Compile SDK: 6.1.0 (API 23)
• Compatible SDK: 6.1.0 (API 23)
• Device Type: Phone

Stage Model 是什么？ HarmonyOS 从 API 9 开始推荐 Stage 模型，它借鉴了 Android 的 Activity 概念，每个 Ability 对应一个独立的功能单元，配合 module.json5 声明式注册。相比 FA（Feature Ability）模型，Stage 更模块化、更容易管理生命周期。

---

三、认识项目结构

项目创建完成后，我们来看一下工程结构：

MyApplication/
├── AppScope/                  # 应用级配置
│   ├── app.json5              # 应用信息（bundleName、版本号等）
│   └── resources/             # 应用级资源
├── entry/                     # 主 Module（entry 类型）
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/           # ArkTS 源码目录
│   │   │   ├── module.json5   # 模块配置文件
│   │   │   └── resources/     # 模块级资源
│   │   ├── mock/              # 模拟数据
│   │   ├── ohosTest/          # 单元测试
│   │   └── test/              # 本地测试
│   ├── build-profile.json5    # 模块构建配置
│   └── oh-package.json5       # 模块包依赖
├── build-profile.json5        # 项目级构建配置
├── hvigor/
│   └── hvigor-config.json5    # hvigor 构建工具配置
├── hvigorfile.ts              # 构建脚本入口
├── local.properties           # 本地 SDK 路径配置
└── oh-package.json5           # 项目级包管理

3.1 核心配置文件解读

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

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

这里定义了应用的包名、版本号、图标等。$media: 和 $string: 是资源引用语法，类似 Android 的 @drawable/ 和 @string/。

build-profile.json5 — 项目级构建配置：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "6.1.0(23)",
        "compatibleSdkVersion": "6.1.0(23)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [ "default" ]
        }
      ]
    }
  ]
}

知识点：HarmonyOS 的 products 概念类似于 Android 的 productFlavors，可以定义多个产品变体（如国内版、海外版）。我们后续如果需要做多渠道打包，就在这里配置。

entry/src/main/module.json5 — 模块配置：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["ohos.want.action.home"]
          }
        ]
      }
    ]
  }
}

这里声明了模块的 Ability（类似 Android 的 Activity），skills 中的 entity.system.home + ohos.want.action.home 表示这是桌面启动入口。

---

四、hvigor 构建系统详解

4.1 hvigor 是什么？

hvigor 是华为自研的构建工具，类似于 Gradle for Android。它使用 Node.js 运行，配置文件是 JSON5 格式。

项目根目录的 hvigor/hvigor-config.json5：

{
  "modelVersion": "6.1.1",
  "execution": {
    "daemon": true,
    "incremental": true,
    "parallel": true
  }
}

三个关键配置：

配置项	作用	建议
daemon	是否启动守护进程（加速后续构建）	开发时开启
incremental	增量编译	开启
parallel	并行编译	多核 CPU 开启

4.2 常用构建命令

# 同步依赖（相当于 Gradle Sync）
hvigorw --sync

# Debug 构建
hvigorw assembleHap --mode debug

# Release 构建
hvigorw assembleHap --mode release

# 清理
hvigorw clean

# 停止 daemon（环境变量变更后建议执行）
hvigorw --stop-daemon

（插入截图：hvigorw --sync 成功输出）

首次 --sync 成功后，你会看到类似输出：

> hvigor Finished :entry:init... after 1 ms 
> hvigor Finished ::init... after 1 ms

这说明工程配置正确、依赖同步成功。

---

五、启动第一个 Hello World

在开始正式开发前，我们先确认模拟器环境能跑起来。

5.1 配置模拟器

DevEco Studio 自带模拟器管理器：

1. 点击顶部工具栏的 Device Manager 图标
2. 创建一个 Phone 模拟器（推荐 API 23）
3. 启动模拟器

5.2 运行项目

点击 Run 按钮（绿色三角），等待编译和部署：

看到模拟器屏幕上显示 “Hello World” 或默认页面，说明开发环境全部就绪。

---

六、本阶段小结

至此，我们已经完成了：

• ✅ DevEco Studio 安装与 SDK 配置
• ✅ DEVECO_SDK_HOME 环境变量配置与 daemon 踩坑解决
• ✅ 创建 HarmonyOS Stage 模型项目
• ✅ 理解完整的项目结构配置文件
• ✅ 掌握 hvigor 构建系统和常用命令
• ✅ 运行项目到模拟器
  

下一篇预告：我们将进入真正的开发环节——为「知墨」笔记应用设计数据层架构，实现 Note 和 Category 领域模型、基于 Preferences API 的持久化仓库，以及清晰的 Clean Architecture 分层。

---

开发工具：DevEco Studio 6.1 | HarmonyOS SDK 6.1.0 | ArkTS + ArkUI