创建你的第一个 HarmonyOS 6 鸿蒙应用 Hello HarmonyOS

我们这篇文章将会在 HarmonyOS 6 的最新环境里，从零把第一个 ArkTS 应用完整跑起来。我们会先把系统与工具版本统一到 6.0.0(20)，再一步一步创建工程、认识目录与关键文件、编写首页与入口绑定、把应用跑到模拟器与真机、扩展成可验证的最小案例。

一、把版本与工具统一到 HarmonyOS 6

我们先把目标版本定准。

HarmonyOS 开发者版本 6.0.0(20) 已经正式发布，版本概览页面写清了发布时间、增强点与与 5.1.1(19) 的承接关系，并且把"ArkUI 能力增强、系统组件新增、多个组件调用细节优化"等变更作为本代重点。我们在动手之前，先对照这份概览确认自己的目标版本与 API 等级，后续查文档与选编译/兼容版本时就能对齐口径。

我们再把开发工具准备齐。HarmonyOS 的一站式 IDE 是 DevEco Studio，它把 HarmonyOS SDK、Hvigor、OHPM、模拟器平台等按套打包，安装完成后，我们可以用 SDK Manager 统一安装 6.0.0(20) 对应的 SDK、构建工具与本地模拟器镜像，减少到处配环境的分散成本。官方"IDE 快速开始"对这些集成组件有明确说明。

我们把命令行侧的工具版本也顺一下。工具链升级指引提醒我们：IDE 升到 6.0.0(20) 后，命令行工具也要同步到同一代，保证流水线构建出的应用包和本地一致，避免"本地能跑、流水线出错"的版本错配。

我们最后准备真机调试的前置条件。我们在设备上开启开发者选项与 USB 调试，在电脑侧准备好 hdc（HarmonyOS Device Connector)。hdc 是官方提供的命令行调试工具，支持设备识别、数据传输、日志查看与应用安装，跨 Windows、Linux、macOS 可用。我们在 IDE 外也能通过它做连通性排查与安装校验。

二、创建第一个工程：选择模板、填准参数、看懂目录

我们在 DevEco Studio 的欢迎页点击 Create Project；如果已经打开过工程，则在菜单选择 File > New > Create Project。

我们选择 Application → Empty Ability，模型保持为 Stage，语言选择 ArkTS。这个模板干净直接，目录层次清楚，适合入门和后续扩展。

官方"从 ArkTS 开始（Stage 模型）"教程与 Hello World Codelab 都采用这条路径。

我们在新建向导里把项目信息填完整：项目名、Bundle Name、保存路径、编译 SDK 与兼容 SDK。

为了对齐 HarmonyOS 6，我们把 Compile SDK 与 Compatible API 都选到 6.0.0(20)/API 20 这一代。

这样生成的模板、组件能力与行为默认与 6.0 文档一致。

我们点 Finish 等 IDE 初始化工程。工程创建好后，默认会有一个 entry 模块，它是可运行的主模块，包含 ArkTS 页面、资源与配置文件。

三、先认识关键文件：UIAbility、页面清单与构建配置

我们把 entry/src/main 展开，会看到 ets 与 resources 两个主目录，以及若干配置与构建文件。我们先把角色分清：

我们先看 UIAbility。UIAbility 是包含界面的应用组件，是系统调度的基本单元，它会为应用提供绘制窗口。

一个应用可以包含一个或多个 UIAbility。生命周期的关键回调包括 onCreate、onWindowStageCreate、onForeground 等，入口 Ability 会在 onWindowStageCreate 里加载首页。

我们知道了这层职责划分，后面就不会把"窗口调度"和"页面显示"混在一起。

我们再看页面清单。

resources/base/profile 里有 main_pages.json（文件名可以自定义，但要和 module.json5 的 pages 标签对应），它用 src 列表声明工程里可被加载的页面路径，第一个条目就是首页。

每次新增页面都要确保它出现在这个清单里。我们通过 IDE 的"New > Page"创建页面时，IDE 会自动写入清单；我们如果手动复制页面文件，就要自己维护这个列表。

我们顺带记住两份构建配置。

module.json5 负责描述模块信息与 Ability 声明；build-profile.json5 与 hvigor 则负责构建目标与流程。

四、写出首页并确认入口绑定

我们打开默认的首页 Index.ets，把它改成一个更直观的界面：一行文字加一个按钮，按钮点击时输出控制台日志。ArkUI 采用声明式写法，我们在 @Entry 与 @Component 装饰器标注的组件里按部件组合界面。

// entry/src/main/ets/pages/Index.ets
@Entry
@Component
struct Index {
  build() {
    Column({ space: 16 }) {
      Text('Hello HarmonyOS,小雨和你一起独立应用开发。')
        .fontSize(12)
        .fontWeight(FontWeight.Medium)
        .margin({ top: 32 })

      Button('点我加油', { type: ButtonType.Capsule, stateEffect: true })
        .onClick(() => {
          console.log('[xiaoyu] Button clicked,加油！')
        })
        .margin({ top: 18 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

我们检查入口绑定是否到位。Stage 模型下，入口 Ability 会在 onWindowStageCreate 中通过 windowStage.loadContent 加载首页；模板工程通常已经把首页与入口绑定好了。我们只要确认 main_pages.json 中包含 "pages/Index" 即可。

五、把应用跑到模拟器与真机，并把日志看清楚

我们先用模拟器验证构建与安装这条链路。打开 Tools → Device Manager，在 Local Emulator 页签新建一个手机或平板模拟器，选择 HarmonyOS 6 的系统镜像。第一次运行会自动拉取并初始化镜像。

我们启动模拟器，在工具栏选择该设备为运行目标，点击运行，控制台看到"Installation succeeded / Launch succeeded"说明安装与启动成功。

我们再用真机做一次完整链路验证。我们在设备里打开开发者选项与 USB 调试，用数据线连接电脑，在 IDE 的设备列表选择该设备并点击运行。如果首次部署提示签名问题，我们回到 Project Structure 的签名配置，开启 HarmonyOS 支持与自动生成调试签名，IDE 会自动为调试构建生成证书与 Profile。这样我们可以先顺畅调试，等准备发布再切换正式签名。

我们把命令行链路也练熟，方便定位顽固问题。我们用 hdc list targets 查看设备是否被识别，用 hdc install 安装 hap 包，用 hdc shell/log 查看日志。官方 hdc 文档把能力范围与常见命令写得很清楚，我们按它的清单逐项验证，遇到 IDE 识别异常也能迅速转到命令行排查。

六、把"Hello"扩展成可验证的最小案例，并学会打包与回归

我们新增一个页面来验证路由跳转。在 IDE 里用 New > Page 创建 Second.ets。我们在首页的按钮点击里调用路由方法跳转到 Second，再在 Second 里提供返回首页的按钮。

// entry/src/main/ets/pages/Index.ets
import { Second } from './Second'

@Entry
@Component
struct Index {
  @Provide('stack') stack: NavPathStack = new NavPathStack()

  @Builder pageMap(name: string) {
    if (name === 'Second') {
      Second() // 映射到下面的 Second 组件
    }
  }

  build() {
    Navigation(this.stack) {
      Column({ space: 16 }) {
        Text('Hello HarmonyOS,小雨和你一起独立应用开发。')
          .fontSize(12)
          .fontWeight(FontWeight.Medium)
          .margin({ top: 32 })

        Button('点我加油', { type: ButtonType.Capsule, stateEffect: true })
          .onClick(() => {
            console.log('[xiaoyu] Button clicked,加油！')
          })
          .margin({ top: 18 })


        Button('进入第二页', { type: ButtonType.Capsule, stateEffect: true })
          .onClick(() => this.stack.pushPath({ name: 'Second' }))
          .margin({ top: 18 })

      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .navDestination(this.pageMap)
  }
}

// entry/src/main/ets/pages/Second.ets

@Component
export struct Second {
  @Consume('stack') stack: NavPathStack

  build() {
    NavDestination() {
      Column({ space: 16 }) {
        Text('第二个页面')
          .fontSize(20)
          .margin({ top: 24 })
        Button('返回首页')
          .onClick(() => this.stack.pop())
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .title("第二页")
  }
}

注意 ：官方已经不推荐使用@ohos.router的方式了，我们使用HarmonyOS 6 推荐的 Navigation.

我们把打包分发的动作走一遍，方便团队内互测。在菜单执行 Build → Build HAP，IDE 会在 out 目录生成 hap 包。我们可以直接用 hdc install 安装，或者在 IDE 中选择设备运行。

配合命令行安装与日志观察，我们能更快覆盖到不同设备的差异。

七、总结

我们已经把"从模板到运行"的完整链路打通：

先锁定 HarmonyOS 6.0.0(20) 的目标版本，再用 DevEco Studio 建工程、装 SDK 与模拟器；我们认识了 UIAbility 的职责与生命周期，知道入口 Ability 在 onWindowStageCreate 加载首页；

我们学会使用 HarmonyOS 6 推荐的Navigation;

我们在模拟器与真机都跑通了首页与日志输出，并且用 hdc 建立了命令行级的排查路径；

我们把"Hello"扩展成了一个包含路由的最小案例，顺手把打包与回归清单也建立了起来。