《2026鸿蒙NEXT纯血开发与AI辅助》第五章：选择成熟方案，创建第一个鸿蒙应用并成功运行-卓伊凡

记住，在各大平台我有配套这个专栏的视频。

上一章我们遇到了一件非常让人抓狂的事情。

在创建 ArkUI-X 跨平台工程的时候，@ohos/hvigor-ohos-arkui-x-plugin 这个依赖包在安装时报错 ERR_PNPM_NO_MATCHING_VERSION，系统要求 4.22.4 版本，但 npm 仓库里最新只到 4.22.3。我们尝试了清理缓存、手动安装指定版本、修改 package.json，但问题在当时就是没有解决。

这件事我也同步反馈给了鸿蒙开发者群。

但是，做教程有一条核心原则我必须遵守：教给你们的每一个操作，都必须是确定能走通的。

所以这一章，我们不纠结，换一条更成熟的路来走。

一、从第四章的报错，我们学到了什么

先做一次复盘。这不是马后炮，而是真正的工程经验总结。

那个报错的表面原因，是依赖版本不存在。但往深一层想，它暴露了一个事实：

ArkUI-X 跨平台方案在当前的版本迭代中，依赖管理还不够稳定。

这不是 ArkUI-X 不好。恰恰相反，它的设计目标非常有价值——一套代码同时编译出 HarmonyOS、Android、iOS 三个平台的应用，这对于有出海需求或者需要覆盖多端用户的团队来说，是实打实的生产力提升。

但问题是，它的实现方式决定了它会引入额外的复杂度。跨平台编译器、平台桥接库（Bridge）、多套构建配置，这些都会增加依赖链的长度。依赖链一长，版本锁定的风险就大，一旦上游仓库的版本更新节奏和工程模板不一致，就会出现我们第四章遇到的那种情况。

所以，一个成熟的开发者应该具备的能力是什么？不是遇到坑就死磕，而是：

根据目标选择最适合的工具链。

如果你的目标是"先把鸿蒙开发学起来"，那就没有必要在环境搭建阶段去挑战最复杂的跨平台方案。先用最稳定的纯鸿蒙原生方案把环境跑通，等整个开发链路都熟了，再回过头来研究 ArkUI-X，那时候你对依赖管理、构建流程的理解已经不一样了，处理问题的能力也会完全不一样。

这就是本章要做的第一个关键决策。

二、回到模板选择：三种成熟的鸿蒙原生方案

我们在第二章详细讲过 DevEco Studio 创建工程时的四个模板。但那次是以要不要跨平台为维度来分类的。这一次，我们把视角切换到**"纯鸿蒙原生开发"**，重新梳理一下你真正可用的选项。

先把表格重新拉出来，帮你回忆：

模板名称	核心目标	运行平台	主要语言
ArkUI-X	跨平台应用	HarmonyOS + Android + iOS	ArkTS (主) + C++ (可选)
ArkUI-X Library	跨平台依赖库	HarmonyOS + Android + iOS	ArkTS (主) + C++ (可选)
ArkUI-X Native C++	跨平台 + 高性能	HarmonyOS + Android + iOS	ArkTS + C/C++
Native C++	鸿蒙原生高性能应用	仅 HarmonyOS	ArkTS + C/C++

但实际在 DevEco Studio 6.0.2 的创建界面里，除了上面这四个，还有一个非常重要的选项我们没有正式介绍过：

Empty Ability。

这个模板在界面上的位置，通常就在 ArkTS 工程分类下面，和 Native C++ 并列。它的特点是：不包含任何跨平台配置，不包含 C++ 模块，只提供一个最干净的 ArkTS + ArkUI 工程骨架。

现在，我们把这三个纯鸿蒙原生方案放在一起，做一个完整对比：

方案一：Empty Ability（默认首选）

适用场景：正常的鸿蒙应用开发，不涉及 C/C++ 代码，不涉及端云一体。

工程特点：

• 只包含 ArkTS 页面代码和资源文件
• 不引入 C++ 编译链，构建速度快
• 依赖关系最简洁，出问题的概率最低
• 是初学者和常规业务开发的最佳起点

选择建议：如果你的应用以 UI 交互和业务逻辑为主，不需要高性能计算或复用 C/C++ 遗留代码，那就选这个。它够用，而且最稳。

方案二：Native C++

适用场景：需要调用系统底层 C/C++ 能力，或者复用已有的 C/C++ 代码库。

工程特点：

• 在 Empty Ability 的基础上，自动创建了 C++ 模块目录
• 包含了 CMakeLists.txt 构建配置
• 支持通过 NAPI（Native API）实现 ArkTS 与 C/C++ 的双向调用
• 适用于音视频编解码、图像处理、游戏引擎、加解密算法等高性能场景

选择建议：如果你确定项目中要用到 C/C++ 能力，不要自己手动去集成，直接选这个模板。它会帮你生成标准的 NAPI 桥接代码和构建配置，省去大量手工配置的时间。

方案三：CloudDev Empty Ability

适用场景：应用需要集成华为云后端服务，做端云一体化开发。

工程特点：

• 在 Empty Ability 的基础上，预置了云开发相关配置
• 集成了认证、云函数、云数据库等服务的 SDK
• 适合需要快速搭建后端能力的项目

选择建议：如果你的应用需要用户登录、数据存储、云函数等后端能力，而且想用华为云的服务，那就选这个。它帮你省去了从零集成云 SDK 的步骤。

三种方案的选择决策树

我帮你整理成一个简单的决策逻辑：

你的应用需要什么？
│
├─ 需要 C/C++ 高性能模块？
│   └─ 是 → 选 Native C++
│
├─ 需要华为云后端服务？
│   └─ 是 → 选 CloudDev Empty Ability
│
└─ 以上都不需要？
    └─ 选 Empty Ability

对绝大多数初学阶段和常规业务开发来说，Empty Ability 就是最合适的选择。

三、本章实战：用 Empty Ability 创建第一个工程

明确了选择逻辑，接下来就是具体操作。

3.1 创建工程

打开 DevEco Studio，如果你还在欢迎页，直接点 Create Project。如果已经在 IDE 里，点 File → New → Create Project。

在模板选择界面，找到 Empty Ability 这个模板，选中它，然后点击 Next。

3.2 填写工程配置

这一步会让你填写一系列配置项。我们第二章讲过，这里再复习一下关键字段：

配置项	说明	示例
Project name	项目名称，建议英文	HelloHarmony
Bundle name	应用包名，反向域名格式，上架后不可改	com.zhuoyifan.helloharmony
Save location	项目保存路径	D:\Projects\HelloHarmony
Module name	入口模块名，默认 entry 即可	entry
Device type	目标设备类型	Phone、Tablet 可按需勾选
Enable Native C++	是否启用 C++ 支持	不勾选（Empty Ability 默认不启用）

这里有一个很容易被忽略但非常重要的细节：Bundle name。

Bundle name 是应用在系统层面的唯一标识符。它的格式遵循反向域名规则：com.公司名.项目名。比如我这里用的是 com.zhuoyifan.helloharmony。

为什么这件事要在创建项目时就定好？

因为 Bundle name 一旦确定，尤其是应用上架之后，就不能再修改了。它在三个层面起作用：

1. 系统识别：鸿蒙系统通过 Bundle name 区分不同的应用，两个应用如果包名相同，系统会认为是同一个应用
2. 签名绑定：应用签名证书是和 Bundle name 绑定的，包名变了，签名就失效
3. 应用市场：华为应用市场上架后，Bundle name 永久锁定

所以创建项目的时候，不要随便写个 com.example.xxx 就过去了。你可以用你自己的域名风格，即使现在没有上架计划，也要养成规范的命名习惯。

填好以后，点 Finish。

3.3 工程创建完成后的第一件事

工程创建完成后，不要急着写代码。先做一件事：

看底部 Build 输出区。

如果你看到类似 BUILD SUCCESSFUL 的输出，说明工程初始化完全正常，依赖也自动安装成功了。

这一次，你不会再看到第四章那种 ERR_PNPM_NO_MATCHING_VERSION 的红色报错。为什么？因为你没有引入 ArkUI-X 的依赖链，整个构建链路走的是最成熟的鸿蒙原生通道。Empty Ability 模板引用的都是鸿蒙原生 SDK 的核心库，这些库的版本经过了充分测试，依赖关系清晰稳定。

这个对比，本身就是很重要的一课。工具的选型，直接决定了你开发体验的起点。

四、Hello World 是怎么出现在屏幕上的

工程创建成功后，DevEco Studio 会自动生成一个默认页面。我们打开 entry/src/main/ets/pages/Index.ets，会看到这样一段代码：

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

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

这段代码虽然简短，但它包含了鸿蒙 ArkUI 声明式开发的四个核心概念。我先做一次拆解，让你知道每一行是干什么的，详细的语法我们后面章节再逐一深入。

4.1 @Entry 装饰器

@Entry 标记这个 struct 是一个页面入口。

在鸿蒙应用里，页面是可以被系统导航和管理的独立单元。一个 .ets 文件里如果有 @Entry，它就注册为一个可路由的页面。每个应用至少有一个 @Entry 页面作为启动页，应用启动时系统会加载它。

4.2 @Component 装饰器

@Component 标记这是一个自定义组件。

在 ArkUI 中，"一切皆组件"是核心设计理念。页面本身是一个组件，页面里的按钮、文本、图片也是组件，你还可以把多个基础组件组合成一个自定义组件。@Component 就是这个自定义组件的声明。

4.3 @State 装饰器与状态驱动 UI

@State message: string = 'Hello World' 这行代码是整个 ArkUI 框架最核心的设计思想之一：状态驱动 UI。

在传统的命令式 UI 开发里，你想改变界面上的文字，你得先找到那个控件，再调用它的 setText() 方法。界面是"被动更新"的。

但在 ArkUI 的声明式范式里，逻辑完全反过来了：

1. 你用 @State 声明一个状态变量
2. 你在 build() 里把 UI 组件绑定到这个状态变量上
3. 当状态变量的值发生变化时，框架自动重新渲染绑定的 UI 组件

Text(this.message) 这行代码把 Text 组件和 message 状态变量绑定在一起。以后无论你在什么时机、因为什么逻辑修改了 this.message 的值，屏幕上显示的文本都会自动更新。你不需要手动操作任何 UI 控件。

这就是声明式 UI 的核心优势：你只管描述 UI 应该长什么样，框架负责把状态同步到界面上。

4.4 build() 方法与声明式 UI 描述

build() 方法是组件的UI 描述函数。它定义了这个组件的界面长什么样。

在 build() 里，你用声明式语法来描述 UI 结构：

• Row() 是一个横向布局容器，子元素沿水平方向排列
• Column() 是一个纵向布局容器，子元素沿垂直方向排列
• Text(this.message) 是一个文本显示组件，显示的内容绑定到 message 状态变量
• .fontSize(50) 设置字体大小为 50 个逻辑像素（vp）
• .fontWeight(FontWeight.Bold) 设置字体粗细为粗体
• .width('100%') 设置宽度占满父容器
• .height('100%') 设置高度占满父容器

这种链式调用语法是 ArkUI 的一大特点。每个组件都支持一系列的属性方法，你通过 . 操作符链式调用，把所有配置写在一段连续的表达里，结构非常清晰。

整个布局的层级关系是这样：

Row (占满整个屏幕)
  └─ Column (占满 Row 的宽度)
       └─ Text (显示 "Hello World"，字号 50，加粗)

五、两种运行方式：模拟器预览与本地真机

代码写好了，接下来是整个开发流程中最有仪式感的一步：运行。

DevEco Studio 提供了两种运行方式，而且这两种方式都不需要外接物理设备，全部在 IDE 内部完成。

5.1 方式一：Previewer 模拟器预览

第一种方式是使用 Previewer，也就是 IDE 内置的 UI 预览器。

这个方式最简单，适合你在写代码的过程中快速看效果：

1. 打开 Index.ets 文件
2. 点击 DevEco Studio 右上角的 Previewer 标签页
3. 系统会自动编译并渲染页面效果

Previewer 的优势是快。你改一行代码，预览区几乎实时更新，不需要完整的编译部署流程。对于 UI 布局调整、组件样式调试，这个方式效率最高。

但它也有局限。Previewer 本质上是一个轻量级的渲染引擎，它不会执行完整的 Ability 生命周期，也不会加载真实的应用运行环境。所以它更适合做"看界面像不像"，而不是"验功能对不对"。官方的要求是电脑显卡需要支持 OpenGL 3.2 或更高版本，如果预览不了，先检查一下显卡驱动。

5.2 方式二：本地真机模拟器运行

第二种方式是使用本地真机模拟器。这是 DevEco Studio 非常强大的一个能力：你可以直接在电脑上下载并运行一个虚拟的华为真机，不需要任何物理设备。

什么意思？就是说你不需要去买一台华为手机，不需要用数据线连接电脑，甚至不需要打开手机的开发者模式。所有的真机调试体验，全部在 DevEco Studio 内部完成。

具体操作步骤：

第一步：打开设备管理器

在 DevEco Studio 顶部工具栏的设备选择下拉框中，点击 Device Manager。

第二步：创建本地真机

在 Device Manager 窗口中，点击 New Emulator。你会看到一个设备列表，包含各种型号的华为真机镜像，比如 Huawei Phone、Huawei Tablet 等等。

第三步：选择设备型号并下载

选择你需要的设备型号，比如 Huawei Phone。如果这个镜像还没有下载过，系统会提示你先下载。镜像文件比较大，第一次下载需要等几分钟，但只需要下载一次，以后就可以直接使用。

第四步：启动本地真机

镜像下载完成后，在 Device Manager 的设备列表里，点击对应设备旁边的启动按钮（三角形图标）。稍等片刻，一个完整的虚拟华为真机就会在你的电脑屏幕上启动。你会看到一个和真实手机一模一样的界面，有桌面、有应用图标、有状态栏，操作方式和真实手机完全一样。

第五步：运行应用

回到 DevEco Studio 主界面，确保顶部设备选择框里选中了你刚启动的本地真机，然后点击绿色的 Run 按钮。

这时候，底部面板会切换到 Run 标签页，输出构建和部署日志。你会看到类似这样的日志流：

> hvigor BUILD SUCCESSFUL
> Installing HAP to device...
> Launching application...

然后，本地真机的屏幕上会自动安装并打开你的应用，Hello World 显示在屏幕上。

5.3 本地真机 vs Previewer：两种方式的本质区别

很多人容易把这两种方式混为一谈，其实它们的定位完全不同：

维度	Previewer 模拟器预览	本地真机模拟器
本质	轻量级 UI 渲染引擎	完整的鸿蒙系统虚拟机
启动速度	极快，近乎实时	需要启动完整的系统，稍慢
运行环境	简化的渲染环境	完整的 HarmonyOS 系统环境
Ability 生命周期	不执行	完整执行
系统 API	部分支持	完整支持
适用场景	UI 布局调试、组件样式调整	功能验证、性能测试、完整交互体验
OpenGL 要求	需要 3.2 以上	需要，但要求更低

一句话概括：Previewer 是"看界面像不像"，本地真机是"验功能对不对"。

5.4 日常开发中的选择策略

理解了两种方式的区别，你在实际开发中就可以灵活切换：

• 日常写 UI 布局的时候，用 Previewer。改完代码立刻看效果，迭代快，效率高。
• 验证页面逻辑、生命周期、系统调用的时候，切到本地真机。它能给你最真实的运行反馈。
• 做性能测试、多设备适配的时候，也一定要用本地真机，因为 Previewer 的性能数据和真实系统有差异。

这个切换策略，能让你在开发效率和质量之间找到最佳平衡。

六、本章完整知识链路总结

这一章的内容，如果用一句话概括就是：

我们从第四章的报错出发，做了一个成熟的技术选型，用 Empty Ability 模板创建了项目，理解了 Hello World 的代码结构，然后通过 Previewer 和本地真机两种方式成功运行。

但如果只是记住操作步骤，那就太浅了。我帮你梳理一下这一章真正的知识链路：

问题复盘（理解 ArkUI-X 依赖报错的本质）
    │
    ▼
技术选型（三种原生方案的完整对比与决策树）
    │
    ▼
工程创建（Empty Ability 模板 + Bundle name 规范）
    │
    ▼
代码解析（@Entry / @Component / @State / build() 的职责与原理）
    │
    ▼
Previewer 预览（轻量级 UI 渲染，快速验证界面效果）
    │
    ▼
本地真机运行（完整 HarmonyOS 虚拟机，真实运行环境验证）
    │
    ▼
策略总结（Previewer 与本地真机的使用场景选择）

这七个环节不是孤立的操作步骤，而是一套完整的思维框架。你以后创建任何一个新项目，都可以套用这个框架：

1. 先明确需求
2. 再选择对应的模板
3. 创建工程，规范配置
4. 理解自动生成的代码结构
5. 用 Previewer 快速验证 UI
6. 用本地真机做完整运行确认
7. 根据场景选择合适的运行方式

把流程固化下来，每一次创建项目都会变得很从容。

七、本章小结

这一章是真正意义上的"分水岭"章节。

在这章之前，你可能还在和环境、报错、模板选择这些"准备工作"打交道。但从这一章开始，你第一次看到了自己写的代码变成了一个真正运行着的鸿蒙应用。

这个跨越，比很多人以为的要重要得多。

更重要的是，这一章你学到了两个核心能力：

第一，理性技术选型的能力。不追新、不盲从，根据自己的实际需求选择最合适的模板。这是从"会抄代码"到"能做项目"的关键一步。

第二，多方式验证的能力。Previewer 快速看效果，本地真机完整验功能，两种方式各有定位，知道什么时候该用什么，这是真正的工程效率。

一个能跑通的项目，意味着你有了一个可以持续实验、持续迭代的基线环境。后面我们学 ArkTS 语法、学 UI 组件、学状态管理、学页面路由，都可以直接在这个项目里动手验证。

下一章开始，我们会正式进入 ArkTS 和 ArkUI 的世界，去拆解组件体系，去理解声明式 UI 的核心设计思想。环境已经稳了，地基已经打好了，接下来就是真正长本事的时候。

我是卓伊凡，鸿蒙开发这条路，你已经正式迈进了大门。下一章见。