鸿蒙原生开发手机：徒步迹 - 项目创建与开发环境配置
从零开始搭建 HarmonyOS NEXT 徒步工具 App，手把手配置开发环境
一、前言
HarmonyOS NEXT 是华为推出的纯血鸿蒙操作系统，彻底剥离了 AOSP 代码，采用全新的 ArkTS 语言和 ArkUI 框架进行原生应用开发。本文将带领大家从零开始搭建"徒步迹"项目的开发环境，包括 DevEco Studio 安装配置、项目创建、模拟器调试等完整流程。
无论你是刚接触鸿蒙开发的新手，还是从 Android/iOS 转过来的开发者，这篇文章都将帮你快速上手。
二、开发环境要求
在开始之前，请确保你的电脑满足以下最低配置要求：
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10/11 64位 / macOS 12+ |
| 内存 | 至少 8GB，推荐 16GB+ |
| 硬盘空间 | 至少 30GB 可用空间 |
| 屏幕分辨率 | 1920x1080 或更高 |
三、安装 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 SDK3.3 配置 SDK
启动 DevEco Studio 后，通过 Preferences → SDK Manager 配置 SDK 路径：
- 设置 HarmonyOS SDK 路径（建议放在用户目录下）
- 勾选安装 API 24 Release 版本
- 安装 OHPM（鸿蒙包管理器）CLI 工具
验证 SDK 安装是否成功：
# 在终端中检查 SDK 版本ls~/Library/Huawei/Sdk/# 检查 ohpm 是否可用ohpm--version四、创建项目
4.1 新建项目
打开 DevEco Studio，点击Create New Project，按以下步骤操作：
- 选择模板：选择Empty Ability模板（Stage 模型）
- 项目配置：
- Project Name：
Tuji（内部项目名） - Bundle Name：
com.hiking.tuji - Save Location：选择你希望的存储路径
- Compatible API：选择API 24
- Language：选择ArkTS
- Device Type：勾选 Phone 和 Tablet
- Project Name：
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 提供了两种调试方式：
- Local Emulator- 本地模拟器（推荐）
- Remote Emulator- 云端模拟器（需登录华为开发者账号）
创建本地模拟器步骤：
- 打开 Device Manager（工具栏图标）
- 点击 “+” 创建新模拟器
- 选择Phone设备类型
- 选择 API 24 Release 系统镜像
- 等待下载并启动模拟器
5.2 真机调试
使用 HarmonyOS 真机调试步骤：
- 开启开发者模式：设置 → 关于手机 → 连续点击版本号 7 次
- 开启 USB 调试：设置 → 系统和更新 → 开发者选项 → USB 调试
- 连接电脑，在 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 语法快速入门
如果你在搭建环境过程中遇到任何问题，欢迎留言交流。