系列：HarmonyOS 开发入门 · 01
说明：本文以 2026 年 8 月 HarmonyOS 官方开发文档为基准。DevEco Studio、SDK 和 API 会持续更新，界面名称可能略有变化，但核心流程基本一致。

刚开始接触鸿蒙时，我不建议先去啃一堆概念。最有效的方式还是把项目跑起来：能创建、能编译、能看到页面，再回头理解 ArkTS、ArkUI、UIAbility，很多东西会顺得多。

这篇只做一件事：从安装环境开始，跑通第一个 ArkTS 工程。

1. 先准备开发环境

HarmonyOS 应用开发主要用到三样东西：

• DevEco Studio：开发 IDE；
• ArkTS：应用开发语言；
• ArkUI：声明式 UI 框架。

安装 DevEco Studio 后，第一次启动通常会引导安装 SDK。这里我的习惯是先使用当前稳定版 SDK，不要一上来为了“新”去混用预览版，否则后面遇到 API 可用性问题会很难判断是代码问题还是环境问题。

如果 SDK 没装完整，可以在 DevEco Studio 的 SDK Manager 里补装。

2. 创建一个 ArkTS 工程

打开 DevEco Studio，选择创建新工程。普通应用入门可以选择一个空白 Ability 模板，然后确认语言为 ArkTS。

项目名例如：

HelloHarmony

包名例如：

com.example.helloharmony

创建完成后，先不要急着改代码，直接编译一次。能正常编译，说明 SDK、Hvigor 和工程环境至少是通的。

3. 找到真正需要关注的代码

初学阶段先记住三个位置就够了：

entry/src/main/ets/
entry/src/main/resources/
entry/src/main/module.json5

ets 目录放 ArkTS 代码，resources 放字符串、图片等资源，module.json5 是模块配置。

默认页面一般在：

entry/src/main/ets/pages/Index.ets

把页面改成最简单的样子：

@Entry
@Component
struct Index {
  @State message: string = 'Hello HarmonyOS'

  build() {
    Column({ space: 16 }) {
      Text(this.message)
        .fontSize(28)
        .fontWeight(FontWeight.Bold)

      Button('点一下')
        .onClick(() => {
          this.message = 'ArkTS 跑起来了'
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这段代码已经包含 ArkUI 最核心的几个概念：组件、状态、声明式 UI、事件。

4. 这几行代码到底在做什么

@Entry 表示这是一个页面入口组件。

@Component 表示当前 struct 是一个 ArkUI 自定义组件。

@State 表示 message 是会驱动 UI 刷新的状态变量。当它发生变化时，依赖它的 UI 会更新。

build() 用来描述界面结构。

如果你之前写过 SwiftUI、Flutter 或 Jetpack Compose，会很熟悉这种思路：不是“创建一个 Label，再修改 Label”，而是描述“当前状态下界面应该长什么样”。

5. 真机和模拟器怎么选

刚开始学布局和基础 API，模拟器完全够用；但涉及相机、相册、系统权限、通知、设备能力时，我更建议尽早上真机。

很多“模拟器正常、真机不正常”的问题，本质上都是系统能力、权限、签名或设备差异导致的。

6. 我建议第一天先做到这一步

不要把第一天目标定成“学会 ArkTS”。这不现实，也没必要。

第一天把下面几件事跑通就很好：

1. 创建工程；
2. 找到 Index.ets；
3. 修改一个文本；
4. 点击按钮更新状态；
5. 跑到模拟器或真机。

把这个闭环跑通以后，再去看项目结构、生命周期、Navigation，会轻松很多。

7. 常见问题

编译一上来就报错

先检查 SDK 是否完整、工程要求的 API 版本是否已安装，再看 Hvigor 依赖。不要第一时间怀疑业务代码。

页面改了但没有变化

确认你修改的是当前启动页面，而不是工程里另一个同名文件；同时注意 Preview 和实际运行环境并不是一回事。

ArkTS 看起来像 TypeScript，是不是直接照 TS 写就行

不是。ArkTS 保留了 TypeScript 的大部分语法风格，但静态检查更严格，一些在 TS 里很灵活的写法在 ArkTS 中会直接报错。下一篇项目结构之后，我会专门讲这个问题。

总结

鸿蒙入门的第一个门槛其实不高：DevEco Studio + ArkTS + ArkUI，把一个最小工程跑通即可。

真正容易让新人迷糊的，反而是后面的工程结构、配置文件、页面和 Ability 生命周期之间的关系。下一篇就先把项目目录拆开来看。