新手友好：DevEco Studio 5.0 新建 HarmonyOS NEXT 工程完整流程

aycxd

110人浏览 · 2026-07-10 19:54:49

aycxd · 2026-07-10 19:54:49 发布

很多新手第一次接触鸿蒙开发，往往在环境搭建和工程创建环节就卡了壳：SDK 装不对、路径有中文报错、新建工程满屏红色、不知道哪个模板对应纯血鸿蒙……本文面向零基础开发者，以 DevEco Studio 5.0 为例，从零开始一步步带你创建一个标准的 HarmonyOS NEXT（API 26）工程，附工程结构详解与常见报错解决方案，照着做就能顺利跑通 Hello World。
在这里插入图片描述

一、前置准备：SDK 先配好，新建工程才不报错

新建工程之前，务必先确认 SDK 环境配置正确，这是 90% 新手报错的根源。

1.1 打开 SDK Manager

打开 DevEco Studio 5.0，在欢迎页或顶部菜单栏进入：

Windows：File > Settings > SDK Manager
macOS：DevEco Studio > Settings > SDK Manager

1.2 安装 HarmonyOS NEXT SDK

在 SDK Manager 中切换到 SDK Platforms 标签页：

勾选 HarmonyOS NEXT 对应版本（推荐 API 26 / 鸿蒙 7.0，能力最完善）
右侧勾选 Phone 等你需要适配的设备类型 SDK
切换到 SDK Tools 标签页，勾选以下必装工具：
- Command Line Tools：命令行工具
- Toolchains：编译工具链
- Emulator：模拟器（需要本地调试则必装）
点击 Apply 开始下载安装，等待完成后点击 OK。

注意：HarmonyOS NEXT 是纯血鸿蒙商用 SDK，区别于 OpenHarmony 开源 SDK。开发面向消费者的鸿蒙应用，请务必安装商用 HarmonyOS SDK，否则会出现 @kit.* 导入报错。

二、正式创建：四步走完新建工程向导

第一步：选择工程模板

在 DevEco Studio 欢迎页点击 Create Project；如果已打开工程，则通过 File > New > Create Project 进入向导。
左侧选择 Application（普通应用），右侧模板选择 Empty Ability（空白能力模板，最适合入门）。
确认模板预览图右侧标注为 Stage 模型，点击 Next。

关键说明：HarmonyOS NEXT 仅支持 Stage 模型，旧版 FA 模型已被彻底移除。所有纯血鸿蒙工程都必须基于 Stage 模型创建，这是硬性前提。

第二步：填写工程基本信息

进入工程配置页，逐项填写如下信息，每一项都有规范，不要随意填写：

配置项	填写说明与规范
Project name	工程名称，由英文字母、数字、下划线组成，首字母必须大写，例如 `MyFirstApp`
Bundle name	应用包名，采用反向域名格式，至少三段，例如 `com.example.myfirstapp`；上架后不可修改，建议提前规划好
Save location	工程保存路径，绝对不能包含中文、空格和特殊字符，否则会导致编译失败
Compile SDK	编译 SDK 版本，选择 HarmonyOS NEXT (API 26) 及以上
Compatible SDK	最低兼容版本，建议与 Compile SDK 保持一致
Language	开发语言，固定选择 ArkTS（HarmonyOS NEXT 唯一主推的开发语言）
Device type	适配设备类型，入门勾选 Phone 即可，后续可扩展平板、折叠屏等

填写完成后，右侧预览区会显示 Hello World 预览效果，确认无误后点击 Finish。

第三步：等待工程初始化与依赖同步

点击 Finish 后，DevEco Studio 会自动生成工程骨架并下载项目依赖，底部状态栏会显示同步进度。

首次创建建议保持网络畅通，IDE 需要拉取构建工具与依赖包，通常耗时 1~5 分钟。
等待底部状态栏出现 Sync completed 且无红色报错，即为初始化成功。

小技巧：如果同步长时间卡住，可以先关闭工程，删除工程目录下的 .idea 和 build 文件夹，重新打开工程触发同步。

第四步：验证工程是否正常

同步完成后，打开左侧项目视图，确认目录结构完整、代码文件无红色波浪线、顶部工具栏的运行按钮为可点击状态，即代表工程创建成功。

三、新手必懂：工程核心目录结构

很多新手创建完工程后面对一堆文件无从下手，其实日常开发只需要关注最核心的几个目录和文件，其余可以暂时不用管。

MyFirstApp
├── entry                     # 主模块（应用入口，绝大多数代码写在这里）
│   ├── src/main
│   │   ├── ets               # ArkTS 源码目录
│   │   │   ├── entryability  # 应用入口，管理应用生命周期
│   │   │   │   └── EntryAbility.ets
│   │   │   └── pages         # 页面目录，所有 UI 页面放这里
│   │   │       └── Index.ets # 首页，我们主要修改的文件
│   │   ├── resources         # 资源目录：图片、字符串、颜色、布局资源
│   │   │   ├── base/media    # 图片资源
│   │   │   └── base/element  # 字符串、颜色等常量
│   │   └── module.json5      # 模块配置文件：权限、Ability、页面路由注册
│   └── build-profile.json5   # 模块编译配置：SDK版本、签名配置
├── app.json5                 # 应用全局配置：包名、版本号、应用名称
└── build-profile.json5       # 工程全局编译配置

三个最常用文件说明

entry/src/main/ets/pages/Index.ets：首页 UI 代码，我们写界面、写逻辑主要在这个文件里。
entry/src/main/module.json5：模块配置文件，新增页面、申请权限、配置 Ability 都要修改它。
build-profile.json5（工程根目录）：编译 SDK 版本配置，升级 SDK 版本主要改这里。

四、跑起来：运行到模拟器验证效果

工程创建完成后，我们把它运行到模拟器上，验证第一个 Hello World 效果。

4.1 创建并启动模拟器

在这里插入图片描述

点击顶部工具栏的设备下拉框，选择 Device Manager。
在弹出的窗口中切换到 Local Emulator，点击 + New Emulator。
选择手机设备型号，点击 Next，选择对应系统镜像（HarmonyOS NEXT API 26），点击 Next。
保持默认配置，点击 Finish 完成模拟器创建。
点击模拟器列表右侧的启动按钮，等待模拟器开机进入桌面。

4.2 运行应用

顶部工具栏确认设备选择为刚才启动的模拟器。
点击绿色三角形运行按钮（或快捷键 Shift + F10）。
等待编译打包完成，应用会自动安装到模拟器并启动。
看到屏幕中央显示 Hello World，即代表工程创建与运行全部成功。

五、修改试试：改一行代码体验热重载

新手可以试着修改一下首页文本，感受 ArkUI 的实时预览与热重载能力：

打开 entry/src/main/ets/pages/Index.ets
找到代码中的 'Hello World'，修改为 '我的第一个鸿蒙应用'
保存文件，模拟器上的应用会自动刷新，文字实时变更

完整首页代码示例：

@Entry
@Component
struct Index {
  @State message: string = '我的第一个鸿蒙应用';

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#F8F9FA')
  }
}

六、新手高频踩坑与解决方案

1. 新建工程后大面积红色报错，提示找不到 @kit

原因：SDK 版本不匹配，或安装的是 OpenHarmony SDK 而非商用 HarmonyOS SDK
解决：打开 SDK Manager 确认安装了 HarmonyOS NEXT SDK；检查工程根目录 build-profile.json5 中 compileSdkVersion 是否为 26.0.0 及以上，runtimeOS 是否为 HarmonyOS。