鸿蒙原生开发手机：徒步迹 - 项目创建与开发环境配置

从零开始搭建 HarmonyOS NEXT 徒步工具 App，手把手配置开发环境

一、前言

HarmonyOS NEXT 是华为推出的纯血鸿蒙操作系统，彻底剥离了 AOSP 代码，采用全新的 ArkTS 语言和 ArkUI 框架进行原生应用开发。本文将带领大家从零开始搭建"徒步迹"项目的开发环境，包括 DevEco Studio 安装配置、项目创建、模拟器调试等完整流程。

无论你是刚接触鸿蒙开发的新手，还是从 Android/iOS 转过来的开发者，这篇文章都将帮你快速上手。

二、开发环境要求

在开始之前，请确保你的电脑满足以下最低配置要求：

三、安装 DevEco Studio

DevEco Studio 是华为官方提供的鸿蒙应用开发 IDE，基于 IntelliJ IDEA 打造。

3.1 下载安装包

访问华为开发者官网下载 DevEco Studio 安装包。当前推荐版本为DevEco Studio 6.1.1 Release（对应 API 24 Release 版本）。

下载地址：华为开发者联盟 - 开发工具 - DevEco Studio

3.2 macOS 安装步骤

# 下载完成后，双击 dmg 文件# 将 DevEco Studio 拖入 Applications 文件夹# 首次启动时需要安装以下 SDK 组件：# - ArkTS SDK (API 24)# - HarmonyOS SDK# - DevEco Testing SDK

3.3 配置 SDK

启动 DevEco Studio 后，通过 Preferences → SDK Manager 配置 SDK 路径：

1. 设置 HarmonyOS SDK 路径（建议放在用户目录下）
2. 勾选安装 API 24 Release 版本
3. 安装 OHPM（鸿蒙包管理器）CLI 工具

验证 SDK 安装是否成功：

# 在终端中检查 SDK 版本ls~/Library/Huawei/Sdk/# 检查 ohpm 是否可用ohpm--version

四、创建项目

4.1 新建项目

打开 DevEco Studio，点击Create New Project，按以下步骤操作：

1. 选择模板：选择Empty Ability模板（Stage 模型）
2. 项目配置：
   • Project Name：Tuji（内部项目名）
   • Bundle Name：com.hiking.tuji
   • Save Location：选择你希望的存储路径
   • Compatible API：选择API 24
   • Language：选择ArkTS
   • Device Type：勾选 Phone 和 Tablet

4.2 项目结构说明

创建完成后的项目结构如下：

Tuji/ ├── entry/ # 主模块 │ ├── src/main/ets/ # ArkTS 源码目录 │ │ ├── entryability/ # Ability 入口 │ │ └── pages/ # 页面文件 │ ├── src/main/resources/ # 资源文件 │ └── src/main/module.json5 # 模块配置文件 ├── build-profile.json5 # 项目级构建配置 ├── oh-package.json5 # 项目级包管理 └── local.properties # 本地环境配置

4.3 配置项目文件

我们的"徒步迹"App 需要修改以下关键配置：

build-profile.json5- 项目级配置：

{ app: { bundleName: "com.hiking.tuji", vendor: "hiking", versionCode: 1000000, versionName: "1.0.0", icon: "$media:app_icon", label: "$string:app_name", compatibleApiVersion: 24, targetApiVersion: 24, }, modules: [ { mainAbility: "EntryAbility", deviceType: ["phone", "tablet"], package: "entry", name: "entry", srcPath: "./entry", }, ], }

module.json5- 模块配置文件（核心）：

{ module: { name: "entry", type: "entry", description: "徒步迹主模块", mainElement: "EntryAbility", deviceTypes: ["phone", "tablet"], pages: "$profile:main_pages", abilities: [ { name: "EntryAbility", srcEntry: "./ets/entryability/EntryAbility.ets", description: "应用主Ability", icon: "$media:app_icon", label: "$string:app_name", startWindowIcon: "$media:app_icon", startWindowBackground: "$color:start_window_background", exported: true, skills: [ { entities: ["entity.system.home"], actions: ["action.system.home"], }, ], }, ], requestPermissions: [ { name: "ohos.permission.LOCATION", reason: "用于记录徒步轨迹和显示当前位置", usedScene: { abilities: ["EntryAbility"], when: "inuse" }, }, ], }, }

五、配置模拟器

5.1 创建模拟器

DevEco Studio 提供了两种调试方式：

1. Local Emulator- 本地模拟器（推荐）
2. Remote Emulator- 云端模拟器（需登录华为开发者账号）

创建本地模拟器步骤：

1. 打开 Device Manager（工具栏图标）
2. 点击 “+” 创建新模拟器
3. 选择Phone设备类型
4. 选择 API 24 Release 系统镜像
5. 等待下载并启动模拟器

5.2 真机调试

使用 HarmonyOS 真机调试步骤：

1. 开启开发者模式：设置 → 关于手机 → 连续点击版本号 7 次
2. 开启 USB 调试：设置 → 系统和更新 → 开发者选项 → USB 调试
3. 连接电脑，在 DevEco Studio 中选择设备运行

六、运行第一个项目

完成上述配置后，点击运行按钮（绿色三角形）编译并启动应用。

首次编译过程可能需要下载 Gradle 依赖和 SDK 资源，耗时约 5-10 分钟。

成功后，模拟器或真机上将显示"Hello World"界面。

七、常见问题

7.1 SDK 下载失败

如果 SDK 下载失败，请尝试：

# 配置国内镜像源（在 oh-package.json5 中添加）{"repository":"https://repo.huaweicloud.com/repository/npm/"}

7.2 编译报错

• “ArkTS syntax error”：检查 ArkTS 语法，注意严格类型检查
• “Resource not found”：检查 $media 和 $string 资源引用是否正确
• “ohpm install failed”：检查网络连接，尝试手动执行ohpm install

八、总结

本文详细介绍了 HarmonyOS NEXT 开发环境的搭建全过程，从 DevEco Studio 安装、项目创建、配置文件编写到模拟器调试。配置好环境后，下一篇文章我们将学习 ArkTS 语言的核心语法，为编写"徒步迹"的各个页面打下基础。

下一篇预告：鸿蒙原生开发手机：徒步迹 - ArkTS 语法快速入门

如果你在搭建环境过程中遇到任何问题，欢迎留言交流。