前言：先让第一个工程运行起来

大家好，我是杨利杰 YJlio。

这是我的 HarmonyOS 7.0 学习笔记第 01 篇。本篇从开发环境开始，整理 DevEco Studio 安装、SDK 配置、创建 ArkTS 工程以及首次运行的检查方法。

做桌面支持和排障时，我习惯先找到问题所在的环节，再处理具体报错。学习应用开发也可以用这个思路：创建工程、同步依赖、编译、安装、启动，每一步都有自己的检查结果。把这些结果记清楚，后面遇到问题就有一条可追溯的路径。

我的练习安排是：先运行 IDE 生成的模板，确认基础环境可用，再修改首页的一段文字，检查修改是否出现在设备上。

第一次练习先建立可复现的运行基线；每次只改一个因素，才能判断问题出在哪一步。

本文配图为根据学习内容制作的示意信息图。IDE 界面、目录细节和选项以实际版本为准；文中的环境版本与运行结果需要在完成实际操作后填写。

一、安装之前，先记录开发环境

DevEco Studio 是华为面向 HarmonyOS 应用及元服务开发提供的集成开发环境。安装包应从华为开发者联盟的 DevEco Studio 资源页获取，并根据官方要求选择适合本机操作系统的版本。

本系列使用“HarmonyOS 7.0 学习笔记”作为名称。实际工程使用哪个 SDK、API 级别和模板，要根据本机配置填写，不能用系列标题代替环境记录。

项目	需要记录的内容	本次记录
操作系统	系统名称、版本与体系结构	待填写
DevEco Studio	IDE 的完整版本号	待填写
HarmonyOS SDK/API	工程实际使用的 SDK 与 API 级别	待填写
工程模板	本次选择的模板名称	待填写
目标设备	模拟器或真机型号、系统版本	待填写
应用包名	工程中实际使用的应用标识	待填写

首次启动 IDE 时，可能还需要下载 SDK、构建工具和模拟器组件。提前检查网络、磁盘空间和下载状态；在依赖仍然下载时，先观察进度和日志。

此处先填写开发环境。同步、构建、启动和页面修改结果，留到第六节完成实际操作后再记录。

二、“装好了”要拆成六项检查

IDE 能打开以后，还需要确认工程能够同步、构建和运行。我会按下面六个环节逐项检查。

环节	检查内容	适合保留的记录
识别工程	IDE 是否打开了正确工程目录	工程名称、目录路径
SDK 就绪	工程所需 SDK 是否可用	SDK 配置与版本
同步完成	依赖同步是否结束，有没有待处理错误	同步输出、首条错误
构建结果	构建任务是否完成	任务名与完整结果
设备连接	模拟器或真机是否出现在运行目标中	目标设备名称、连接状态
应用启动	应用是否安装并进入预期首屏	实际设备画面与启动日志

IDE 安装完成，只能说明工具已安装；首屏运行需要另外验证。

如果工程同步失败，就先处理同步错误；如果构建成功但找不到设备，就检查设备连接。这样记录比直接反复重装整个开发环境更容易保留排错线索。

三、创建一个最小 ArkTS 工程

第一次创建工程时，我会选择当前 IDE 提供的基础 HarmonyOS 应用模板，保留生成的页面和入口代码，先验证模板本身能否运行。

1. 选择应用模板、语言与目标设备

打开新建工程入口，按照本次用途选择应用模板、ArkTS 技术栈和目标设备类型。不同 IDE 版本的模板名称、分类和选项可能变化，需要按实际界面辨认。

ArkTS 是鸿蒙生态的应用开发语言，入门资料可从华为官方 ArkTS 页面查阅。本文练习使用 ArkTS 页面，暂时不添加额外业务模块。

2. 核对工程信息

配置项	本次练习的处理方式
工程名	使用简短、容易辨认的名称，例如 HarmonyFirst
包名	练习可采用 com.example.harmonyfirst；正式应用按自身发布要求设置
保存路径	选择稳定、简短的独立目录，避免后续随意移动
SDK	选择本机已安装、且当前模板支持的版本
目标设备	与本次准备运行的模拟器或真机匹配

创建完成后，等待依赖同步结束。同步尚未完成时，不宜同时更换多个 SDK 版本，否则会增加排查变量。

四、先认识工程中几个常用位置

模板生成后，我会先确认页面源码、Ability 入口、资源和模块配置分别放在哪里。此时不需要记住所有配置项，但要知道修改页面时应该查看哪个文件。

部分	入门阶段先理解的作用
entry 模块	常见模板中的应用入口模块，具体模块名以工程为准
ArkTS 页面	描述页面布局和交互的源码位置
Ability 入口	查看应用启动与页面加载相关代码
资源目录	存放图片、字符串等应用资源
模块配置	查看模块信息、能力和相关配置声明

本节图示围绕当前应用模块，展示页面、Ability 入口、资源与模块配置的功能关系。它不表示实际文件的目录层级；修改前，应在本机工程中确认完整路径，尤其要区分同名页面和不同模块。

先找到当前运行模块使用的页面，再修改文本；文件名相同，不代表就是同一个运行入口。

五、用一段文本理解 ArkTS 页面

首次运行时，先保留模板原样。模板能够启动后，再在对应页面中修改一处文本，并重新运行。这一步用来确认源码文件与设备画面之间的对应关系。

下图对应两个 Text 的页面示例，展示 build()、Column、文本字号和居中布局之间的关系。图后的代码保留原稿示例。

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('HarmonyOS 学习笔记：第一个页面')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
      Text('先确认模板可运行，再添加功能。')
        .fontSize(16)
        .margin({ top: 12 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

build() 中的组件组织描述页面内容；Column 把子组件按纵向排列，两个 Text 用来展示文字；后面的样式方法设置字号、间距和布局。本节图示的手机页面与上方代码对应：第一段是“HarmonyOS 学习笔记：第一个页面”，第二段是“先确认模板可运行，再添加功能。”，两段文字组成的内容在页面中居中排列。

这段代码属于页面结构示例。放入工程时，应核对当前模板的页面写法和 SDK 支持情况，保留模板已有的入口与必要导入。若属性、枚举或组件声明报错，先查看对应 API 文档和模板代码。

入门练习优先只替换模板中的一段文字，不要同时覆盖页面、入口和工程配置。

六、首次运行，按顺序核对结果

我会把第一次运行拆成两轮。第一轮运行未修改的模板；第二轮只改一处首页文本，确认修改生效。

第一轮：验证模板基线

1. 打开工程，等待同步结束，检查是否仍有下载或错误。
2. 启动目标模拟器，或连接已完成调试授权的真机。
3. 在运行配置中选择正确模块和目标设备。
4. 执行运行操作，查看构建和安装结果。
5. 在设备上核对实际首屏，同时保留需要的日志与截图。

第二轮：验证单点修改

1. 找到当前运行模块使用的首页文件。
2. 将一段文本改为容易辨认的新内容，保存文件。
3. 重新构建并运行，确认部署完成。
4. 核对设备是否显示新内容，记录结果。

记录项	实际操作后的填写方式
模板首次构建	填写构建结果；失败时记录任务名和首条错误
应用首次启动	填写能否进入首屏及实际表现
文本修改	填写新文本是否出现在设备上
未解决问题	记录现象、已检查事项与下一步

下面这张记录表的左页对应第一节的环境信息，右页对应本节的同步、构建、启动和文本修改结果。两部分都按实际情况填写。

步骤写完不等于运行成功。只有实际构建结果、设备画面和日志，才能支持结果记录。

七、同步和构建失败时，先找第一条错误

同步一直没有结束

先查看同步输出，判断是在持续下载、等待网络响应，还是已经失败。检查下载源和代理设置是否符合当前环境要求，保留有上下文的错误信息。

如果下载仍有进展，先等待当前任务；如果有明确错误，就针对该错误处理。同步问题尚未查清时，反复切换 SDK 会让原因更难区分。

教程中的模板名称找不到

根据 HarmonyOS 应用类型、ArkTS 技术栈和目标设备筛选当前模板。再检查生成的工程是否具备本次需要的页面、入口和模块配置。旧教程的名称可以作为线索，实际界面和官方说明才是配置依据。

还没改代码，构建就失败

优先确认 SDK 是否可用、同步是否结束，再看首个失败任务属于配置、依赖还是源码编译。保存完整的第一段错误和任务名称，最后一行的“失败”提示往往不足以定位问题。

我会记录四件事：当时在做什么、第一条错误是什么、已经检查了什么、下一步准备只改哪个因素。这样再次运行时，结果才便于比较。

八、设备和页面问题，分别检查

模拟器启动了，IDE 没有运行目标

确认模拟器已经完全启动，并能被设备管理功能识别。不要仅凭模拟器窗口出现就认定连接已完成。

真机调试按当前设备系统完成开发者选项设置和授权。检查实际连接状态，先保存日志和设备状态，再尝试重新连接。

修改了文字，设备仍显示旧页面

按照“文件—保存—构建—部署—画面”的顺序检查。确认改的是当前运行模块使用的页面，文件已保存，本次构建和部署均完成。

可以临时使用一段明显不同的文本，排除改错文件或看错页面的情况。这次练习尚未引入动态状态逻辑，先检查基础运行链路。

学习总结

第一篇练习的目标，是建立一个能重复验证的最小开发环境。我会先确认 IDE、SDK、同步、构建、设备连接和应用启动，再用一处文本修改验证源码与画面的关系。

完成实际练习后，补齐环境表、运行结果和真实截图。如果某一步还没完成，就保留“待验证”的记录，并写清当前问题。

把每一步的结果记录清楚，比一次修改很多设置更有助于后续排错。

下一篇将进一步查看 entry 模块、ArkTS 页面、Ability 入口、资源目录与模块配置，继续通过小范围修改理解工程结构。

参考资料

1. 华为开发者联盟：DevEco Studio 资源与开发工具
2. 华为开发者联盟：ArkTS 语言

---

声明：本文为学习笔记与操作方法整理，配图为示意信息图；实际工具版本、工程界面与运行结果以本机操作和官方文档为准。

返回顶部