系列文章《鸿蒙开发从入门到专家》第 1 篇（初级篇）
前言
2024 年华为正式推出 HarmonyOS NEXT，业内称之为"纯血鸿蒙"——它彻底移除了 Android 兼容层，从内核到应用框架全部自研。到 2026 年，HarmonyOS 终端设备已突破 8000 万台，覆盖手机、平板、PC、车机、智慧屏等全场景。对于开发者来说，这意味着一个独立于 Android 和 iOS 之外的第三大生态正在快速成型，而 ArkTS + ArkUI 就是打开这个生态的钥匙。
很多有经验的 Android 或前端开发者想转入鸿蒙开发，却被第一步的环境搭建拦住了。本文从下载安装到运行第一个应用，手把手带你走完整流程，大约 15 分钟就能出成果。
一、DevEco Studio NEXT 安装与配置
1.1 下载与安装
DevEco Studio 是华为官方提供的鸿蒙应用集成开发环境，基于 IntelliJ IDEA 社区版打造。2025 年后的项目必须使用 DevEco Studio NEXT（对应 API Level 12+）。
系统要求：
Windows 10/11（64 位，8GB 内存以上）
macOS 11 及以上（Intel 或 Apple Silicon）
硬盘空间至少 20GB
下载地址： 华为开发者联盟官网（developer.huawei.com/consumer/cn/deveco-studio）
安装过程与 Android Studio 几乎一致，一路下一步即可。首次启动时会提示下载 SDK，建议选择：
HarmonyOS SDK（API 12 及以上）
Previewer 预览器（强烈推荐，支持热重载）
Emulator 模拟器（如果没有真机调试的话）
1.2 创建第一个项目
打开 DevEco Studio，选择 File → New → Create Project，在模板列表中选择 Empty Ability（Stage 模型）。这里注意：华为已主推 Stage 模型，旧的 FA 模型逐渐淘汰，新项目直接选 Stage 即可。
填写项目信息：
Project name：HelloHarmonyOS
Bundle name：com.example.helloharmonyos
Save location：自选目录
Compatible SDK：API 12（对应 HarmonyOS 5.0）
Model：Stage
点击 Finish，等待 Gradle 同步完成。首次同步可能需要 3-5 分钟，取决于网络状况。
1.3 项目结构速览
同步完成后，你会看到如下目录结构：
HelloHarmonyOS/
├── entry/ # 主模块（entry 是默认入口模块名）
│ ├── src/main/ets/
│ │ ├── entryability/
│ │ │ └── EntryAbility.ets # 入口 Ability，管理页面生命周期
│ │ └── pages/
│ │ └── Index.ets # 首页（我们主要编辑的文件）
│ ├── src/main/resources/ # 资源文件（图片、字符串、颜色）
│ │ ├── base/element/ # 颜色、字符串等值资源
│ │ └── rawfile/ # 原始文件
│ ├── module.json5 # 模块配置（权限、Ability 声明等）
│ └── build-profile.json5 # 构建配置
├── hvigor/ # 构建脚本
└── build-profile.json5 # 项目级构建配置
关键文件说明：
EntryAbility.ets：Stage 模型的入口，负责窗口管理和生命周期回调。Index.ets：首页页面文件，ArkUI 声明式 UI 代码写在这里。module.json5：相当于 Android 的 AndroidManifest.xml，声明 Ability、权限、路由等信息。
二、编写第一个 ArkUI 页面
2.1 认识 ArkUI 声明式语法
打开 entry/src/main/ets/pages/Index.ets，默认会生成一段示例代码。我们把它改成自己的第一个页面：
@Entry
@Component
struct Index {
@State message: string = 'Hello HarmonyOS!'
@State count: number = 0
build() {
Column({ space: 20 }) {
Text(this.message)
.fontSize(28)
.fontWeight(FontWeight.Bold)
.fontColor('#317AF7')
Text(`点击次数: ${this.count}`)
.fontSize(20)
.fontColor('#666666')
Button('点我计数', { type: ButtonType.Capsule })
.width(160)
.height(44)
.backgroundColor('#317AF7')
.fontColor(Color.White)
.onClick(() => {
this.count++
})
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.backgroundColor('#F5F5F5')
}
}
语法要点解读：
2.2 实时预览与热重载
DevEco Studio 提供了强大的预览功能。点击编辑器右上角的 Previewer 按钮，即可在右侧看到实时渲染效果。修改代码后，预览器会自动热重载，无需重新编译——这个体验比 Android 的 XML 预览器流畅得多。
如果你没有真机，可以配置模拟器：
点击顶部工具栏的 Tools → Device Manager
选择 Remote Emulator（华为云模拟器，需要登录华为账号）
或者创建 Local Emulator（本地下载镜像，启动较慢）
2.3 运行到真机
如果你手头有搭载 HarmonyOS 5.0 的手机，真机调试效果最好：
手机开启开发者模式：设置 → 关于手机 → 连续点击版本号 7 次
开启 USB 调试：设置 → 系统和更新 → 开发人员选项 → USB 调试
用 USB 线连接电脑，DevEco Studio 会自动识别设备
点击顶部运行按钮（绿色三角），选择你的设备
首次运行需要在手机上允许调试授权。编译安装大约 10-20 秒，比 Android 的 Gradle 构建快不少。
三、理解 Stage 模型的核心概念
很多从 Android 转过来的开发者会困惑：鸿蒙的 Ability 到底是什么？跟 Android 的 Activity 有什么区别？
3.1 Ability vs Activity
UIAbility 是 Stage 模型的核心组件，每个 UIAbility 对应一个独立的窗口。简单应用通常只有一个 EntryAbility，复杂应用可以有多个 Ability（比如一个主页面 Ability + 一个视频播放 Ability）。
3.2 生命周期钩子实战
打开 EntryAbility.ets，你可以在 onWindowStageCreate 里获取窗口并加载首页：
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'
import { window } from '@kit.ArkUI'
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
console.info('EntryAbility onCreate')
}
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('EntryAbility onWindowStageCreate')
// 加载首页
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
console.error('Failed to load content', err.message)
return
}
console.info('Succeeded in loading content')
})
}
onForeground(): void {
console.info('EntryAbility onForeground')
}
onBackground(): void {
console.info('EntryAbility onBackground')
}
}
onForeground 和 onBackground 分别对应应用进入前台和退到后台的时机，可以用来处理播放暂停、数据保存等逻辑。
四、常见踩坑与解决
问题 1：预览器报错 “Unable to start preview”
检查 SDK 版本是否与项目配置的 API 级别匹配
尝试 Build → Clean Project 后重新同步
问题 2：真机安装提示 “解析包失败”
检查手机的 HarmonyOS 版本是否 >= 项目配置的 minCompatibleVersionCode
确认签名配置正确（自动签名可在 File → Project Structure → Signing Configs 中开启）
问题 3：@State 变量修改后 UI 不刷新
ArkTS 要求状态更新必须是赋值操作，
this.arr.push(item)不会触发刷新，要写成this.arr = [...this.arr, item]
小结与下篇预告
本文带你完成了 DevEco Studio 的安装、第一个 ArkUI 项目的创建和运行，并介绍了 Stage 模型的核心概念。关键记住三点：
新项目一定选 Stage 模型，FA 模型已淘汰
ArkUI 是声明式框架，数据驱动 UI，状态用
@State管理预览器支持热重载，开发效率很高
下一篇（第 2 篇）我们将深入 ArkTS 语言本身——如果你已经会 TypeScript，60% 的内容你已经掌握了。但鸿蒙在 TypeScript 基础上增加了声明式 UI 语法、状态装饰器和严格类型模式，这些才是重点。