你有没有遇到过这种情况：装了 DevEco Studio 但第一步就卡住了？项目创建了但不知道代码往哪写？Hello World 跑起来报错却找不到原因？这篇文章，把以上问题全部解决，跟着做，保证 15 分钟跑通你的第一个 HarmonyOS 应用。

---

一、90%的人会踩的5个坑（先看这个）

正式开始之前，先把这5个坑列出来——如果你正准备动手，大概率会碰到其中几个：

序号	报错信息	发生场景	解决难度
1	No targetSdkVersion configured	首次运行	⭐
2	OpenGL版本不足	模拟器启动	⭐⭐
3	code: 956834 install parse native so failed	安装时报错	⭐⭐
4	EntryAbility not found	代码修改后	⭐
5	Sync completed 卡死 / 模拟器无响应	依赖下载	⭐⭐⭐

遇到问题直接跳到第六节查找对应解决方案。下面开始正题。

---

二、DevEco Studio下载安装（图文详解）

HarmonyOS 的御用 IDE 是 DevEco Studio，基于 IntelliJ IDEA Community 定制，对中文开发者非常友好。

2.1 下载地址

📎 点击访问 DevEco Studio 官方下载页

选择对应系统的版本（Windows / macOS / Linux），下载完成后一路 Next 安装即可。

2.2 安装前必须知道的3件事

❌ 踩坑1：Windows 用户安装路径含中文 —— 后果：后续编译各种诡异报错

✅ 正确做法：安装到纯英文路径，比如 D:\DevEcoStudio，不要有任何中文或空格。

❌ 踩坑2：首次启动后 SDK 下载卡住 —— 原因：国内网络直连华为服务器较慢

✅ 正确做法：提前配置网络代理，或使用手机热点进行首次下载（实测速度提升明显）。

❌ 踩坑3：macOS 提示"无法验证开发者"

✅ 正确做法：系统设置 → 隐私与安全性 → 滑到下方找到对应的 App，允许运行即可。

2.3 配置 Node.js

ArkUI 项目构建依赖 Node.js（要求 >= 18.x），打开终端验证：

node -v   # 要求 >= 18.x
npm -v

没有安装？去 nodejs.org 下载 LTS 版本。

2.4 创建第一个模拟器

DevEco Studio 自带模拟器（Device Manager），按以下步骤创建：

Tools → Device Manager
  → 右下角设置图标（配置存储路径，建议放在空间充足的盘）
  → New Emulator
    → 设备类型选 Phone（入门推荐）
    → 系统镜像选 API 12+ 版本
    → 内存分配 4GB 以上
  → 下载镜像，等待完成

💡 模拟器 vs 真机：入门阶段用模拟器完全够用（适合 UI 开发调试）；真机调试用于验证相机、蓝牙、传感器等硬件能力。后续实战阶段再上真机。

---

三、创建第一个ArkTS项目

3.1 新建工程

打开 DevEco Studio，按以下步骤操作：

File → New → Create Project
  ↓
选择 "ArkTS Application"（声明式UI模板）
  ↓
填写信息：
  - Project Name: HelloHarmony
  - Bundle Name: com.example.helloharmony（包名，上架后不可改）
  - Save Location: 选择非中文路径
  - API Version: 12（推荐，使用最新声明式API）
  ↓
点击 Finish

3.2 等待依赖同步

首次创建，DevEco 会自动下载 HarmonyOS SDK 和项目依赖。底部状态栏看到进度条，可能需要 3-10 分钟，耐心等待 Sync completed 出现再继续。

⚠️ Sync 卡死的解决方案：关闭 DevEco → 删除项目目录下的 .idea 和 build 文件夹 → 重新打开项目 → 重新 Sync。

---

四、Hello World代码逐行解析

项目创建完成后，找到入口文件：

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%')
  }
}

逐行解释这三个装饰器：

装饰器	作用	规则
@Entry	标记这个组件是页面入口（一个页面只能有一个）	必写
@Component	标记这是一个 UI 组件	必写
@State	组件内部可变的"记忆"——值变化时，UI 自动重新渲染	需要更新的变量才加

💡 @State 是什么：想象成组件的"私有记忆"。this.message = 'Hello, HarmonyOS!' 改完之后，UI 自动刷新，不需要手动调用任何 render 函数。

4.1 写一个带交互的Hello World

把代码改成这样——点击文字会变成 “Hello, HarmonyOS!”，还有一个计数器：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  @State count: number = 0

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .fontColor('#1890ff')
        .onClick(() => {
          this.message = 'Hello, HarmonyOS!'
        })

      Text('点击次数: ' + this.count)
        .fontSize(20)
        .fontColor('#666')
        .margin({ top: 20 })

      Button('点我计数')
        .fontSize(20)
        .margin({ top: 20 })
        .onClick(() => {
          this.count++
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

---

五、运行项目：模拟器 vs 真机

方式一：模拟器（推荐新手）

1. 顶部工具栏选刚才创建的模拟器
2. 点击 ▶ Run（或按 Shift + F10）
3. DevEco 自动编译并安装到模拟器
4. 看到效果后，点击文字和按钮试试

方式二：真机

1. 手机打开开发者模式：设置 → 关于手机 → 连续点击版本号 7 次
2. 开发者选项中打开 USB 调试
3. 数据线连接电脑，手机点击"允许 USB 调试"
4. 设备下拉框选手机型号，点击 Run

---

六、项目结构：一图说清楚（收藏备用）

HelloHarmony/
├── AppScope/                       # 应用全局配置
│   └── app.json5                   # 应用名、版本号、图标
├── entry/                          # 主模块
│   └── src/main/
│       ├── ets/
│       │   ├── entryability/      # 应用生命周期入口
│       │   │   └── EntryAbility.ets
│       │   └── pages/
│       │       └── Index.ets       # 首页入口 ← 你主要改这里
│       ├── module.json5             # 模块配置（声明权限等）
│       └── resources/             # 资源目录（图片、字符串）
├── build-profile.json5             # 构建配置
├── hvigorfile.ts                  # 构建脚本
└── oh-package.json5               # 依赖管理（类似 package.json）

文件	作用	你需要操作吗？
Index.ets	页面入口，每个 @Entry 就是一个页面	✅ 主要是这里
EntryAbility.ets	应用主入口，管理生命周期	⚠️ 进阶后需要
module.json5	声明有哪些页面和权限	⚠️ 加新页面时需要
resources/	图片、字符串等资源	⚠️ 加图片时需要

---

七、5个常见报错+解决方案

Q1：首次运行报错 “No targetSdkVersion configured”

原因：build-profile.json5 缺少 targetSdkVersion 字段。

解决：在 products 数组中添加：

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "compatibleSdkVersion": "5.0.0(13)",
    "targetSdkVersion": "5.0.0(13)"
  }
]

保存后点右上角 Sync Now。

---

Q2：模拟器启动失败，提示"OpenGL版本不足"

解决：

1. 升级显卡驱动到最新版本
2. Windows 用户：控制面板 → 程序 → 启用 Hyper-V 和 虚拟机平台
3. 电脑配置一般：降低模拟器分辨率和内存

---

Q3：安装时报错 “code: 956834 install parse native so failed”

原因：abiFilters 未包含模拟器架构。

解决：在 build-profile.json5 中添加：

"abiType": "normal",
"buildOption": {
  "nativeLib": {
    "abiFilters": ["arm64-v8a", "x86_64"]
  }
}

---

Q4：修改代码后模拟器没有更新？

解决：Ctrl + S 保存触发热更新，或点击工具栏的 H 热更新按钮。新增页面等重大修改需要重新 Run。

---

Q5：提示 “EntryAbility not found”

原因：module.json5 没有正确声明入口 Ability。

解决：检查 module.json5 的 abilities 数组是否包含：

{
  "name": "EntryAbility",
  "srcEntry": "./ets/entryability/EntryAbility.ets",
  ...
}

---

八、恭喜你跑通了第一个HarmonyOS应用！

从零开始，你完成了：

• ✅ 安装配置 DevEco Studio
• ✅ 创建第一个 ArkTS 项目
• ✅ 写出了带交互的 Hello World
• ✅ 理解了 @Entry / @Component / @State 三大装饰器
• ✅ 跑通模拟器 / 真机
• ✅ 解决了 5 个常见报错

如果这篇文章有帮助，点赞 + 收藏，我们下篇讲 ArkTS 状态管理——帮你从 Hello World 进阶到真正写应用。

有什么问题，评论区见！

---

💬 欢迎在评论区分享你遇到的问题，我会尽量解答。如果觉得有帮助，欢迎转发给想学鸿蒙的朋友！

📅 发布日期：2026-05-28 | 适合读者：零基础开发者 | 预计阅读时间：15分钟