第一章：开发环境搭建
本章配套代码：
code/Chapter1对应技术栈：DevEco Studio 2026 + API 26 + HarmonyOS 7.0 + 状态管理（第一章 V1 入门，第二章起 V2）
1.1 学习目标
- 了解 HarmonyOS 应用开发的基本概念与生态
- 掌握 DevEco Studio 2026 的安装、配置与工程结构
- 创建并运行第一个 HarmonyOS 应用
- 熟悉 DevEco Studio 常用快捷键与实时模板配置
- 完成经典页面跳转案例（两页面 + router 跳转/返回，官网入门写法）
- 认识声明式 UI 的基本形态（第一章 V1 入门，第二章起 V2）
1.2 HarmonyOS 概述
HarmonyOS 是华为自主研发的面向万物互联时代的全场景分布式操作系统，可运行于手机、平板、手表、智慧屏、车机等多种设备。
┌─────────────────────────────────────────┐
│ HarmonyOS 生态 │
│ 手机 平板 手表 智慧屏 车机 … │
│ ┌───────────────────────────────────┐ │
│ │ 一次开发，多端部署（One-for-All） │ │
│ │ 分布式能力（数据/任务/设备协同） │ │
│ │ 声明式UI（ArkUI + ArkTS） │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
核心特性：
| 特性 | 说明 | 应用场景 |
|---|---|---|
| 一次开发，多端部署 | 一套代码适配多种设备 | 手机/平板/折叠屏 |
| 分布式能力 | 设备间数据与任务协同 | 多设备数据同步、跨端流转 |
| 声明式UI | 数据驱动界面更新 | ArkUI 声明式开发范式 |
| V2状态管理 | 新一代状态管理机制 | 组件状态、全局状态、深度观测 |
1.3 开发工具链
DevEco Studio 是 HarmonyOS 应用开发的官方 IDE，基于 IntelliJ IDEA 定制，提供：
- 代码编辑、智能提示、实时预览
- 编译、打包、签名
- 本地模拟器与真机调试
- Previewer 预览器（无需模拟器即可预览 UI）
- 性能分析、内存检测工具
开发语言与框架关系：
┌──────────────────────────────────────┐
│ 应用层（你的代码） │
│ ┌────────────┐ ┌───────────────┐ │
│ │ ArkTS │ │ ArkUI │ │
│ │ 编程语言 │ │ 声明式UI框架 │ │
│ └────────────┘ └───────────────┘ │
├──────────────────────────────────────┤
│ HarmonyOS SDK（API 26） │
│ 系统服务 / 分布式能力 / 安全框架 │
├──────────────────────────────────────┤
│ 内核 / 系统 │
└──────────────────────────────────────┘
1.4 安装 DevEco Studio
1.4.1 系统要求
| 项目 | Windows | macOS |
|---|---|---|
| 系统版本 | Windows 10/11 64位 | macOS 11+（Apple Silicon/Intel） |
| 内存 | 16GB 及以上（推荐 32GB） | 16GB 及以上 |
| 硬盘 | 100GB 及以上（SSD 推荐） | 100GB 及以上（SSD 推荐） |
| 分辨率 | 1280×800 及以上 | 1280×800 及以上 |
1.4.2 下载与安装
- 访问 华为开发者官网 → 开发工具 → DevEco Studio 下载中心
- 选择 Windows 版本安装包下载
- 双击安装包，一路 Next 完成安装
- 安装完成后，桌面出现 DevEco Studio 图标
💡 提示：安装路径不要包含中文与空格，推荐安装到非系统盘，如
D:\program\DevEco Studio。
1.4.3 首次启动配置
- 启动 DevEco Studio，选择 Do not import settings（首次使用）
- 进入欢迎页后，等待 SDK 组件初始化
- 若未自动安装 SDK，可进入 File > Settings > SDK 手动配置
1.5 配置开发环境
1.5.1 检查 SDK
DevEco Studio 内置 HarmonyOS SDK，位于安装目录的 sdk 文件夹。
API 版本对应关系（本课程使用 API 26）：
| 项目 | 版本 |
|---|---|
| DevEco Studio | 2026 版本 |
| API Version | 26 |
| compatibleSdkVersion | "26.0.0" |
| 运行时 | HarmonyOS 7.0 |
⚠️ 注意：在
build-profile.json5中，API 26 的compatibleSdkVersion/targetSdkVersion必须写成"26.0.0"（带补丁号），不能写成"26"，否则工程无法正确同步。
1.5.2 环境诊断
通过菜单 Help > Diagnostic Tools > Diagnose Development Environment 检查：
- JDK 版本是否满足要求
- SDK 路径与版本是否正常
- Node.js 与 hvigor 工具链是否可用
- 模拟器镜像是否就绪
1.5.3 创建模拟器
- 打开 Tools > Device Manager
- 点击 + New Emulator（若无镜像，先下载）
- 选择设备类型：Phone（本课程统一使用手机模拟器）
- 选择 API Version：26
- 下载模拟器镜像（约 2-3GB，需耐心等待）
- 点击 Finish 完成创建
💡 模拟器启动后，可通过
adb devices（HarmonyOS 使用hdc）验证连接，输出类似127.0.0.1:5555 device即表示已连接。
1.6 创建第一个应用
1.6.1 创建项目
- 欢迎页点击 Create Project
- 选择 Application > Empty Ability
- 填写工程信息：
| 配置项 | 值 | 说明 |
|---|---|---|
| Project name | FirstApp | 工程名称 |
| Bundle name | com.example.firstapp | 应用唯一标识 |
| Compatible SDK | 26 | API 版本 |
| Module name | entry | 默认模块名 |
| Device type | Phone | 目标设备 |
1.6.2 工程结构
HarmonyOS 工程采用 App（应用）+ Module（模块） 两级结构：
FirstApp/
├── AppScope/ # 应用级配置（全局）
│ ├── app.json5 # 应用配置：bundleName、图标、版本
│ └── resources/ # 应用级资源
│ └── base/
│ ├── element/ # 字符串、颜色等
│ └── media/ # 图标图片
├── entry/ # 模块目录
│ ├── build-profile.json5 # 模块构建配置
│ ├── hvigorfile.ts # 模块构建脚本
│ ├── oh-package.json5 # 模块依赖
│ └── src/
│ ├── main/
│ │ ├── ets/
│ │ │ ├── entryability/ # 应用入口 Ability
│ │ │ │ └── EntryAbility.ets
│ │ │ ├ ── entrybackupability/ # 备份能力
│ │ │ └── pages/
│ │ │ └── Index.ets # 首页页面
│ │ ├── resources/ # 模块资源
│ │ │ └── base/
│ │ │ ├── element/ # 字符串、颜色、样式
│ │ │ ├── media/ # 图片资源
│ │ │ └── profile/ # 页面配置等
│ │ └── module.json5 # 模块配置（权限、Ability声明）
│ └── ohosTest/ # 测试代码
├── build-profile.json5 # 工程构建配置（SDK版本、签名）
├── oh-package.json5 # 工程级依赖（modelVersion）
├── hvigorfile.ts # 工程构建脚本
└── hvigor/
└── hvigor-config.json5 # hvigor 构建工具配置
关键配置文件说明：
| 文件 | 作用 | 关键字段 |
|---|---|---|
AppScope/app.json5 | 应用级配置 | bundleName、icon、label |
build-profile.json5 | 构建配置 | compatibleSdkVersion、signingConfigs |
oh-package.json5 | 依赖管理 | modelVersion |
module.json5 | 模块配置 | abilities、requestPermissions |
1.6.3 第一个页面（V1 写法）
刚入门的第一个页面，直接用 Empty Ability 模板默认的 V1 写法（与官网一致），等熟悉后再过渡到 V2。模板自动生成的首页如下：
// Index.ets —— 模板生成的默认首页
@Entry
@Component
struct Index {
@State message: string = 'Hello World'
build() {
Column({ space: 20 }) {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
// ① 添加按钮，点击修改 message
Button('点击我')
.onClick(() => {
this.message = 'Welcome to HarmonyOS!' // ② 状态变化，UI 自动刷新
})
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
V1 语法要点（本章入门认识即可）：
@Entry：页面入口标识@Component：组件装饰器@State：组件内部状态，数据变化自动刷新 UI- 声明式写法：UI 由
build()中的组件树描述，状态驱动更新
🔑 本课程的写法约定：第一章是官方入门体验，使用 V1（
@Component/@State，与官网模板一致）；从第二章起本课程统一采用 V2 状态管理（@ComponentV2+@Local等装饰器），届时会系统讲解，此处先不展开。
💡 本章的最终案例（页面跳转）见 1.7 节，完整代码见
code/Chapter1。
1.6.4 运行应用
- 启动模拟器（或连接真机并开启开发者模式）
- 点击工具栏绿色 Run 按钮（或
Shift+F10） - DevEco 自动完成：同步 → 编译 → 签名 → 安装 → 启动
- 模拟器中看到应用界面即运行成功
🔧 首次运行会执行 hvigor 同步，需下载依赖，耗时较长，请耐心等待。
1.7 经典案例：页面跳转（第一个应用）
🎯 本案例完全照搬华为官方《使用 ArkTS 语言开发（Stage 模型）》入门案例，采用官方最简单的 router 路由 + V1 写法（
@Entry/@Component/@State，路由经getUIContext().getRouter()获取，见 1.7.3 写法说明），让刚装好环境的第一课同学专注把"第一个能跳转的应用"跑起来。完整代码见code/Chapter1。
⚠️ 重要说明：本案例是官方入门体验，特意使用 V1 + router；从第二章开始本课程统一采用 V2 + Navigation（见 1.6.3 的写法约定）。两种写法都能运行、互不冲突，同学们先感受"页面能跳转"，后续章节再系统学习正式写法。
1.7.1 新建第二个页面
- 在 Project 窗口，右键
entry > src > main > ets > pages - 选择 New > Page > Empty Page，命名为
Second，点击 Finish - 用这种方式创建，DevEco 自动在路由表
main_pages.json中注册了新页面
💡 若用 New > ArkTS File 创建（纯文件、无页面模板），则需手动在
main_pages.json中注册路由，见 1.7.2。
1.7.2 配置页面路由（main_pages.json）
router 按 url 跳转，所有页面都必须在路由表中注册。打开 entry > src > main > resources > base > profile > main_pages.json：
{
"src": [
"pages/Index",
"pages/Second"
]
}
🔑
pages/Second就是跳转时用的 url，页面文件与 url 一一对应，新增页面记得在这里注册。
1.7.3 首页 Index.ets（跳转）
⚠️ 写法说明：旧版教程直接
import { router } from '@kit.ArkUI'使用 router 模块，该写法在新版 DevEco Studio 中会提示过时/不推荐。官方最新写法不再直接导入 router，而是通过this.getUIContext().getRouter()获取路由实例，编辑器不再告警。本课程一律采用官方最新写法。
打开 entry > src > main > ets > pages > Index.ets，改成：
// Index.ets
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State message: string = 'Hello World';
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
// 添加按钮，以响应用户onClick事件
Button() {
Text('Next')
.fontSize(30)
.fontWeight(FontWeight.Bold)
}
.type(ButtonType.Capsule)
.margin({
top: 20
})
.backgroundColor('#0D9FFB')
.width('40%')
.height('5%')
// 跳转按钮绑定onClick事件，单击时跳转到第二页
.onClick(() => {
console.info(`Succeeded in clicking the 'Next' button.`)
// 获取UIContext
let uiContext: UIContext = this.getUIContext();
let router = uiContext.getRouter();
// 跳转到第二页
router.pushUrl({ url: 'pages/Second' }).then(() => {
console.info('Succeeded in jumping to the second page.')
}).catch((err: BusinessError) => {
console.error(`Failed to jump to the second page. Code is ${err.code}, message is ${err.message}`)
})
})
}
.width('100%')
}
.height('100%')
}
}
🔑
this.getUIContext()获取当前页面的 UI 上下文，uiContext.getRouter()返回路由实例，pushUrl({ url: 'pages/Second' })按 url 跳转到已 注册页面，.then/.catch处理成功/失败回调。
💡 按钮文字与背景色这里直接用字面量（
'Next'、'#0D9FFB'），方便初学者理解；把文字/颜色统一放进资源文件用$r引用是更规范的做法，后续章节再介绍。
1.7.4 第二页 Second.ets（返回）
// Second.ets
@Entry
@Component
struct Second {
@State message: string = 'Hi Second';
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() {
Text('Back')
.fontSize(25)
.fontWeight(FontWeight.Bold)
}
.type(ButtonType.Capsule)
.margin({
top: 20
})
.backgroundColor('#0D9FFB')
.width('40%')
.height('5%')
// 返回按钮绑定onClick事件，点击按钮时返回到第一页
.onClick(() => {
console.info(`Succeeded in clicking the 'Back' button.`)
// 获取UIContext
let uiContext: UIContext = this.getUIContext();
let router = uiContext.getRouter();
// 返回到第一页
router.back();
})
}
.width('100%')
}
.height('100%')
}
}
🔑 与首页一致：先获取 UIContext，再
getRouter()拿到路由实例，router.back()返回上一页。
1.7.5 运行验证
- 启动模拟器，点击工具栏 Run 运行
- 首页点击 Next → 跳转到第二页
- 第二页点击 Back → 回到首页
- 也可用 Previewer 预览验证跳转效果
🔧 本案例最终代码见
code/Chapter1（Index.ets+Second.ets）。
运行效果截图：
1.8 IDE 高效操作（快捷键与实时模板）
参考：鸿蒙学苑-环境搭建（05 常用快捷键、06 实时模板）。第一课先熟悉这些高频操作，写代码事半功倍。
1.8.1 常用快捷键
| 快捷键 | 功能 |
|---|---|
Ctrl + Alt + L | 格式化代码（写代码必备） |
Ctrl + Y | 删除当前行 |
Ctrl + D | 复制当前行 |
Shift + Enter | 切换下一行（光标无需在行尾） |
Ctrl + Alt + O | 清除多余导包 |
Ctrl + B / Ctrl + 左键 | 进入方法/变量的定义处 |
Ctrl + F12 | 弹出当前文件结构（快速跳转方法） |
Ctrl + F / Ctrl + R | 当前文件查找 / 替换 |
Ctrl + [ / Ctrl + ] | 跳到花括号开始 / 结束 |
Ctrl + + / Ctrl + - | 展开 / 收缩代码块 |
Ctrl + 鼠标滚轮 | 缩放代码字体 |
Shift + F6 | 重命名文件（选中文件） |
Ctrl + Alt + S | 打开设置 |
Ctrl + Alt + Shift + S | 项目结构（签名/版本配置） |
💡 更多自定义：
Settings > Keymap中可按自己习惯修改快捷键（如从 VS Code 转来的同学可把格式化改为Alt + Shift + F）。
1.8.2 实时模板（Live Templates）
写代码时反复出现的固定片段，可提前配置成缩写，输入缩写 + 回车即自动展开，大幅提升效率。
配置入口： Settings > Editor > Live Templates
模板语法：
$END$：展开后光标停留位置- 自定义变量（如
$FILE_NAME$）：展开时可交互填写
1）todo 待办注释
在编写代码时，通常会有不同的业务逻辑待完成，暂时用 todo 注释标注，可在 TODO 窗口中查看和定位。配置代码片段，输入缩写 + 回车即可快速生成：
// TODO $FILE_NAME$ 待完成: $END$
2）点击事件 & 箭头函数
编写代码过程中会频繁使用点击事件和箭头函数，配置成代码片段可提高开发效率。
点击事件（自定义快捷键，例如 ock）：
.onClick(() => {
$END$
})
箭头函数（自定义快捷键，例如 jt）：
($END$) => {
}
3）诗词数组（pmarr）
马老师在授课过程中，可能会用到很多诗词。整理成数组，避免每次准备，以提高效率（自定义快捷键 pmarr）：
pmArr: string[] = [
`我醉欲眠卿且去 明朝有意抱琴来`,
`卡布奇诺今犹在 不见当年倒茶人`,
`时来运转皆同力 运去英雄不自由`,
`堪笑一场梦颠倒 元来此生恰浮云`,
`再见少年拉满弓 不惧岁月不俱风`,
`我今因病魂颠倒 唯梦闲人不梦君`,
`君埋泉下泥削骨 我寄人间雪满头`,
`南来北往徒自老 故人稀`,
`日拱一卒无有尽 功不唐捐终入海`,
`何事人间频乞食 此心已是负彩霞`,
`峨眉山月半轮秋 影入平羌江水流`,
`天生我才必有用 千金散尽还复来`,
`垂杨紫陌洛城东 今年花胜去年红`,
`劝君莫负艳阳天 恩爱欢愉趁少年`,
`何须浅碧深红色 自是花中第一流`,
`山有木兮木有枝 心悦君兮君不知`,
`曾经沧海难为水 除却巫山不是云`,
`玲珑骰子安红豆 入骨相思知不知`,
`直道相思了无益 未妨惆怅是清狂`,
`金风玉露一相逢 便胜却人间无数`,
`从此无心爱良夜 任他明月下西楼`,
`欲寄彩笺兼尺素 山长水阔知何处`,
`若似月轮终皎洁 不辞冰雪为卿热`,
`得成比目何辞死 愿作鸳鸯不羡仙`,
]
4）初始化背景（bj）
NEXT 版本默认初始化页面结构为相对布局 RelativeContainer，授课偏好列布局，可配置默认代码片段（自定义快捷键 bj）：
Column({ space: 30 }) {
$END$
}
.width('100%')
.height('100%')
.backgroundColor($r('app.color.theme_color'))
.justifyContent(FlexAlign.Center)
⚠️ 注意，此处背景颜色引用了资源文件
theme_color，应先去resources > base > element > color.json中设置该颜色值。
5）外部暴露子组件（zj）
开发中经常抽取自定义子组件到指定目录中进行结构分离，此时需要使用 export default 关键字，避免重复编写（自定义快捷键 zj）：
@Component
export default struct $END$ {
build() {
}
}
6）配置文件导出/导入
更多实时模板代码片段可根据需求自行配置。若编辑器卸载重装或更换电脑，重新配置习惯的代码片段很费时，可将配置文件导入/导出以备后用：
- 导出配置：
File > Manage IDE Settings > Export Settings... - 导入配置：
File > Manage IDE Settings > Import Settings... - 恢复默认：
File > Manage IDE Settings > Restore Default Settings...
更多实时模板配置见：鸿蒙学苑-实时模板
1.9 调试基础
日志输出
console.log('调试信息') // Info 级别
console.warn('警告信息') // Warn 级别
console.error('错误信息') // Error 级 别
在 DevEco Studio 底部 Log 面板可查看输出，支持关键字过滤。
断点调试
- 点击代码行号左侧空白处设置断点（红色圆点）
- 点击 Debug（甲虫图标）启动调试
- 程序运行到断点处暂停，可在 Debugger 面板查看变量值
- 使用 Step Over（F8）/ Step Into（F7）单步执行
Previewer 预览
无需启动模拟器，点击页面右上角 Previewer 分栏即可实时预览 UI，修改代码自动刷新，适合快速开发调试。
1.10 常见问题
Q：工程同步报错 The root node of hvigor lock yaml is null？
- 说明工程缺少
oh-package-lock.json5或 hvigor 配置不完整 - 解决：确保工程包含完整的
hvigor/hvigor-config.json5、oh-package.json5、oh-package-lock.json5，然后 File > Sync and Refresh Project
Q：编译报错 compatibleSdkVersion 不合法？
- 检查
build-profile.json5中版本是否写为"26.0.0"（必须含补丁号） - 检查
modelVersion与 DevEco 版本匹配（API 26 对应"5.0.0"）
Q：模拟器启动失败？
- 检查 BIOS 是否开启 Intel VT / AMD-V 虚拟化
- 检查模拟器镜像是否下载完成
- 尝试 Device Manager 中冷启动（Cold Boot）
Q：应用安装了但打开闪退？
- 查看 Log 面板中的 Error 日志
- 检查是否缺少网络权限（后续章节会用到）
- 检查代码中是否有 V1/V2 装饰器混用
1.11 本章小结
| 收获 | 说明 |
|---|---|
| 认识 HarmonyOS | 全场景分布式操作系统，一次开发多端部署 |
| 掌握工具链 | DevEco Studio 2026 + API 26 + hvigor |
| 理解工程结构 | AppScope + entry 两级结构 |
| 运行首个应用 | 从创建到运行完整流程 |
| 经典页面跳转案例 | router 两页面跳转/返回 + main_pages.json 路由注册 |
| IDE 高效操作 | 常用快捷键 + 实时模板（Live Templates） |
| 声明式 UI 入门 | V1（@Component/@State），第二章起统一 V2 |
1.12 课后练习
- 完成 DevEco Studio 安装与模拟器创建
- 创建 Hello World 应用并运行到模拟器
- 修改首页
@State message内容，观察 UI 联动刷新 - 完成 1.7 页面跳转案例：首页 → 第二页 → 返回
- 为首页按钮添加
onClick修改@State message文本，观察 UI 联动刷新 - 在 Live Templates 中配置
todo/ 点击事件模板并试用（练习 1.8.2 的缩写） - 尝试用 Previewer 预览页面并设置断点调试