HarmonyOS 应用开发环境搭建与 DevEco Studio 配置

网罗开发
（小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》 图书作者：《SwiftUI 入门，进阶与实战》 超级个体：COC上海社区主理人 特约讲师：大学讲师，谷歌亚马逊分享嘉宾 科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员 👋 大家好，我是展菲！ 📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。 📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。 💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。 📅 最新动态：2025 年 3 月 17 日 快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

• • 前言
  • 环境要求与前置准备
  • 安装 DevEco Studio
  • SDK 与工具链配置
  • • 设置 SDK 路径
    • 必装 SDK 组件
    • 关键配置项说明
  • 模拟器与真机调试
  • • 创建与启动模拟器
    • 真机调试要点
  • 项目结构与 Gradle 配置
  • • 关键目录与文件
    • 构建配置要点
  • 常见问题与排查思路
  • 总结

前言

刚开始接触 HarmonyOS 应用开发时，很多人会卡在环境搭建这一步：SDK 下载慢、模拟器启动失败、真机调试连不上等等。这些问题其实都有对应的解决方案，只是官方文档比较分散，新手容易踩坑。

今天我们就来梳理一下 HarmonyOS 应用开发环境的完整搭建流程，重点讲 DevEco Studio 的安装、SDK 配置、以及开发中常用的几项设置。不追求完整可运行的 Demo，只把关键步骤和容易出错的地方说清楚。

环境要求与前置准备

在安装 DevEco Studio 之前，需要先确认本机环境是否满足要求。HarmonyOS 开发对系统和硬件有一定要求，忽略这些往往会导致后续模拟器卡顿或编译失败。

系统要求：

• 操作系统：Windows 10 及以上、macOS 10.14 及以上
• 内存：建议 8GB 以上，跑模拟器建议 16GB
• 磁盘：至少预留 10GB 空间给 SDK 和模拟器镜像

前置软件：

• Node.js：DevEco Studio 内置了部分能力，但部分脚手架和工具链会用到 Node，建议安装 LTS 版本（如 18.x）
• Git：用于版本管理和部分模板拉取

Node 和 Git 的安装不在此展开，装好后在终端能正常执行 node -v 和 git -v 即可。

安装 DevEco Studio

DevEco Studio 是华为官方提供的 HarmonyOS 应用开发 IDE，基于 IntelliJ IDEA，熟悉 JetBrains 系列的同学会很快上手。

下载与安装：

首次启动配置：

首次启动时会提示导入设置（有旧版可导入）、选择主题等，按需选择即可。接着会进入 SDK 下载与配置 向导，这一步非常关键。

SDK 与工具链配置

SDK 是开发 HarmonyOS 应用的核心，包含 API、系统镜像、工具链等。配置不当会导致「找不到 SDK」「模拟器无法创建」等问题。

设置 SDK 路径

建议将 SDK 放在单独目录，便于管理和备份，例如：

• Windows：D:\\HarmonyOS\\sdk
• macOS：/Users/你的用户名/HarmonyOS/Sdk

在 DevEco Studio 中：File → Settings → SDK（macOS 为 DevEco Studio → Preferences → SDK），在 HarmonyOS 选项卡下设置 SDK Location 为上述路径。

注意： 路径中不要有中文和空格，否则部分 NDK 或命令行工具可能异常。

必装 SDK 组件

在 SDK 管理界面中，建议至少安装以下内容：

若网络较慢，可优先只装当前项目用到的 API 版本和 Toolchains，Emulator 可后续再装或使用真机调试。

关键配置项说明

在 Settings → SDK 里还有几项容易忽略：

• Proxy：若公司网络需要代理才能访问外网，在此配置 HTTP/HTTPS 代理，否则 SDK 和模拟器镜像可能下载失败
• Auto-download：可关闭「自动下载缺失组件」，改为在报错时手动选择下载，便于控制网络和磁盘占用

模拟器与真机调试

开发阶段通常用模拟器或真机。模拟器依赖 SDK 中的系统镜像，真机则需要开启开发者模式并连接电脑。

创建与启动模拟器

在 Tools → Device Manager 中可创建 AVD（虚拟设备）：

创建完成后点击运行即可启动模拟器。若启动失败，可检查：

• 本机是否开启虚拟化（Intel VT-x / AMD-V），可在任务管理器或「关于」中查看
• 杀毒软件或防火墙是否拦截了模拟器进程

真机调试要点

真机调试前需在手机上：

DevEco Studio 顶部设备下拉框中应出现该设备，选择后即可运行和调试。若未识别，可检查数据线是否支持数据传输、是否安装了对应机型的 USB 驱动（Windows 上较常见）。

项目结构与 Gradle 配置

新建项目时，DevEco Studio 会生成标准 HarmonyOS 工程结构。了解其中几个关键文件，有助于后续排错和定制。

关键目录与文件

entry/ # 主模块，应用入口
src/
main/
ets/ # ArkTS 源码
resources/ # 资源文件
oh-package.json5 # 依赖声明（类似 package.json）
build-profile.json5 # 模块构建配置

oh-package.json5 中声明应用依赖，例如：

{
"name": "entry",
"version": "1.0.0",
"dependencies": {
"@ohos/axios": "^2.0.0",
"@ohos/hypium": "1.0.6"
}
}

依赖安装通过 ohpm 完成，在项目根目录执行 ohpm install 即可（或使用 IDE 的同步依赖按钮）。

构建配置要点

build-profile.json5 中会指定 compileSdkVersion、targetSdkVersion 等，需与 SDK 中已安装的 API 版本一致，否则会报「找不到 API」类错误。例如：

{
"apiType": "stageMode",
"buildOption": {
"arkOptions": {
"compileSdkVersion": 10,
"runtimeOS": "HarmonyOS"
}
}
}

修改这里后，建议在 File → Sync and Refresh Project 做一次同步，避免缓存导致编译异常。

常见问题与排查思路

遇到报错时，优先看 DevEco Studio 底部 Build 或 Event Log 中的具体信息，再根据关键词搜索官方文档或社区。

总结

HarmonyOS 应用开发环境以 DevEco Studio + HarmonyOS SDK 为核心。搭建时重点做好三件事：正确安装并配置 SDK 路径、按需安装 API 与模拟器镜像、理清模拟器与真机调试的前置条件。同时注意 SDK 路径无中文、网络受限时配置代理，能避免大部分环境类问题。后续文章会在此基础上讲解 ArkTS 语法、页面开发与网络请求等具体开发内容。