01 鸿蒙 NEXT 开发环境搭建完全指南DevEco Studio 5.0前言工欲善其事必先利其器。在正式开发鹿鹿·笔迹心理分析这款 HarmonyOS NEXT 原生应用之前我们需要搭建一套完整的鸿蒙开发环境。本文将从DevEco Studio 的下载安装到SDK 配置、项目创建、模拟器运行手把手带你完成 HarmonyOS NEXT 开发环境的全套配置。即使你完全没有鸿蒙开发经验按照本文的步骤也能在 30 分钟内运行起第一个鸿蒙应用。系列源码仓库harmony-appGitHubHarmonyOS NEXT 官方开发指南developer.huawei.com图DevEco Studio 5.0 完整 IDE 界面包含代码编辑器、预览器、Profiler 和设备管理器一、开发环境要求1.1 硬件要求在安装 DevEco Studio 之前请确认你的开发机满足以下最低要求配置项Windows 最低要求macOS 最低要求推荐配置操作系统Windows 10/1164位macOS 13.0macOS 14 或 Windows 11内存8 GB8 GB16 GB 及以上硬盘空间30 GB 可用空间30 GB 可用空间SSD 50 GB处理器Intel i5 / AMD Ryzen 5Intel Core i5 / Apple M1M2/M3 或 Intel i7分辨率1280×8001280×8002K 及以上注意HarmonyOS 模拟器对 GPU 有一定要求建议使用独立显卡或 Apple Silicon 芯片的 Mac以获得更流畅的模拟器体验。1.2 软件依赖DevEco Studio 安装前需要先准备以下软件Node.js18.x 或 20.x LTS 版本下载地址nodejs.orgGit2.30 版本用于版本管理git-scm.comJava 运行环境DevEco Studio 内置 JDK无需单独安装二、DevEco Studio 安装2.1 下载 DevEco Studio访问 华为开发者官网 DevEco Studio 下载页选择对应操作系统的安装包.exefor Windows.dmgfor macOS当前推荐版本DevEco Studio 5.0.3 Build Version: 5.0.3.900WindowsmacOS访问华为开发者官网下载 DevEco Studio 5.0操作系统?下载 .exe 安装包下载 .dmg 安装包双击安装选择安装路径拖入 Applications 文件夹启动 DevEco Studio首次启动配置向导下载 HarmonyOS SDK配置完成创建第一个项目2.2 首次启动配置安装完成后首次启动DevEco Studio 会触发配置向导同意许可协议阅读并同意 HarmonyOS 开发者许可协议选择主题推荐选择 Dark深色主题长时间编码眼睛更舒适配置代理可选若网络访问华为服务器较慢可配置代理SDK 下载向导会自动引导你下载 HarmonyOS SDK约 2-4 GB# DevEco Studio 安装完成后的目录结构macOS/Applications/DevEco-Studio.app/ ├── Contents/ │ ├── bin/# 可执行文件│ ├── jbr/# 内置 JDKJava 17│ ├── plugins/# IDE 插件│ └── lib/# 核心库提示首次安装建议预留充足时间SDK 下载需要较稳定的网络整个配置过程约需 20-40 分钟。三、HarmonyOS SDK 配置3.1 SDK Manager 配置打开 DevEco Studio 后通过Settings → SDK Manager配置 SDKDevEco Studio Settings └── SDK Manager ├── HarmonyOS SDK Location: ~/Library/HarmonyOS/SdkmacOS 默认路径 ├── SDK Platforms │ ├── ✅ HarmonyOS 5.0.0 (API 12) — 本系列主要版本 │ └── ✅ HarmonyOS 5.0.2 (API 13) — 推荐同时安装 └── SDK Tools ├── ✅ Command Line Tools ├── ✅ Toolchains └── ✅ Emulator3.2 SDK 版本说明本系列项目使用的 SDK 版本信息如下字段值说明compatibleSdkVersion6.1.0(23)最低兼容版本API 23targetSdkVersion6.1.1(24)目标编译版本API 24runtimeOSHarmonyOS运行时操作系统arkTSVersion1.0ArkTS 语言版本{app:{products:[{name:default,runtimeOS:HarmonyOS,compatibleSdkVersion:6.1.0(23),targetSdkVersion:6.1.1(24)}]}}版本说明6.1.0(23)是 SDK 版本6.1.0与 API 级别23的组合表示法对应 HarmonyOS NEXT API 23。四、项目创建4.1 新建 HarmonyOS 项目在 DevEco Studio 欢迎界面点击Create Project在创建向导中选择以下配置配置项推荐选择说明TemplateEmpty Ability空白模板最适合从头学习Project TypeApplication标准应用非元服务/原子化服务LanguageArkTS鸿蒙原生开发语言推荐Compatible SDK6.1.0(23)本系列使用的最低 SDKModelStageStage 应用模型推荐现代化模型Bundle Namecom.xxx.xxx应用包名全局唯一标识符4.2 项目基础配置文件项目创建后有两个关键配置文件需要理解AppScope/app.json5应用级配置{app:{bundleName:com.handwriting.analysis,vendor:handwriting,versionCode:1000000,versionName:1.0.0,icon:$media:app_icon,label:$string:app_name,distributedNotificationEnabled:false}}应用级 build-profile.json5构建配置{app:{signingConfigs:[],products:[{name:default,runtimeOS:HarmonyOS,compatibleSdkVersion:6.1.0(23),arkTSVersion:1.0,targetSdkVersion:6.1.1(24)}],buildModeSet:[{name:debug},{name:release}]},modules:[{name:entry,srcPath:./entry,targets:[{name:default,applyToProducts:[default]}]}]}关键配置字段说明bundleName应用包名需在华为开发者联盟注册格式为倒置域名versionCode整数版本号如1000000 1.0.0每次发版必须递增versionName用户可见版本号字符串如1.0.0compatibleSdkVersion最低兼容 SDK决定应用支持的最老鸿蒙版本五、hvigor 构建系统5.1 hvigor 简介HarmonyOS 使用hvigor作为构建工具类似 Android 的 Gradle配置文件为hvigor/hvigor-config.json5{modelVersion:5.0.0,dependencies:{ohos/hvigor-ohos-plugin:^5.0.0}}5.2 常用构建命令# 在 DevEco Studio Terminal 中执行# 清理构建缓存hvigor clean# 构建 debug HAP 包hvigor assembleHap# 构建 release HAP 包hvigor assembleHap--moderelease# 安装到连接的设备hdc shell aa start-aEntryAbility-bcom.handwriting.analysis# 查看设备列表hdc list targetshvigor 构建的主要产物debug HAP用于调试包含调试符号无需签名release HAP用于发布需要签名证书APP Pack多个 HAP 打包后的应用包用于上架应用市场提示DevEco Studio 内集成了构建工具栏日常开发通常直接使用 IDE 的运行按钮无需手动执行 hvigor 命令。六、模拟器配置与运行6.1 创建模拟器通过Tools → Device Manager创建 HarmonyOS 模拟器点击Create virtual device选择设备类型Phone推荐 Huawei Mate 60 系列规格选择系统镜像HarmonyOS 5.0.0 (API 12)配置硬件参数RAM: 4GB存储: 8GB# 模拟器内存分配建议Phone 模拟器配置 RAM:4096MB最低推荐8192MB 内部存储:8GB 分辨率:1080×2340(FHD)像素密度:420dpi6.2 运行第一个 App完成项目创建后按以下步骤运行在 DevEco Studio 工具栏选择已创建的模拟器点击绿色▷ Run按钮或快捷键CtrlR/CmdR等待 HAP 构建和安装首次约需 1-3 分钟模拟器屏幕上将显示默认的Hello World页面运行过程中的日志查看// EntryAbility.ets 中的日志输出import{hilog}fromkit.PerformanceAnalysisKit;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(0x0000,HelloWorld,%{public}s,Ability onCreate);}}在 DevEco Studio 的HiLog窗口中可以实时查看日志输出支持按 TAG 过滤。七、真机调试配置7.1 连接真机如果需要在真实鸿蒙设备上调试需要额外配置开启开发者模式在手机设置 → 关于手机连续点击版本号 7 次启用 USB 调试开发者选项 → USB 调试连接电脑使用数据线连接设备管理器中选择通过 USB 传输文件安装签名证书在华为开发者联盟申请调试证书详见第 18 篇7.2 HDC 命令行工具HDCHarmonyOS Device Connector是华为提供的设备连接工具类似 Android 的 ADB# 查看已连接的设备hdc list targets# 安装 HAP 到设备hdc-t[device_id]install./entry/build/default/outputs/default/entry-default-signed.hap# 查看设备日志hdc-t[device_id]hilog-TAPP# 进入设备 Shellhdc-t[device_id]shell注意真机调试需要华为开发者联盟账号和调试证书新手可以先用模拟器学习待需要测试相机、NFC 等硬件功能时再切换真机。八、常见问题排查8.1 SDK 下载失败常见原因及解决方案网络超时配置 DevEco Studio 网络代理Settings → Appearance Behavior → System Settings → HTTP Proxy磁盘空间不足清理系统缓存确保至少 20 GB 可用空间权限问题macOS以管理员权限运行安装程序8.2 模拟器无法启动错误信息原因解决方案Emulator failed to start虚拟化未开启BIOS 中开启 Intel VT-x / AMD-VHAXM installation requiredHAXM 未安装SDK Manager 中安装 HAXMEmulator out of memory内存不足减少其他应用内存占用或增加模拟器 RAM8.3 构建报错 ArkTS 编译失败# 常见 ArkTS 编译错误error TS6059: File...is not underrootDir.# 解决检查 tsconfig.json 的 rootDir 配置error: Cannotreadpropertyxxxof undefined# 解决检查空值安全使用可选链 this.xxx?.yyy总结本文完整介绍了 HarmonyOS NEXT 开发环境的搭建流程环境准备硬件要求、Node.js 和 Git 安装DevEco Studio 安装下载、安装、首次配置向导SDK 配置通过 SDK Manager 安装目标 API 版本项目创建Stage 模型 ArkTS 语言 Empty Ability 模板模拟器运行创建虚拟设备运行第一个 Hello World真机调试HDC 工具、开发者模式、签名证书常见问题网络、内存、编译错误的排查方案至此你已经拥有了一套完整的鸿蒙 NEXT 开发环境可以开始探索后续的应用开发之旅。一句话记忆DevEco Studio 5.0 SDK API 14 模拟器 鸿蒙 NEXT 最小可用开发套件。确保三者版本对齐是避免 99% 初期问题的关键。下一篇预告第02篇 Stage 应用模型深入解析UIAbility 生命周期如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源HarmonyOS NEXT 官方文档DevEco Studio 下载安装Node.js 官方下载ohpm 包管理器HarmonyOS SDK 配置指南模拟器使用指南HDC 命令参考第00篇 开篇与项目总览第02篇 Stage应用模型
01 鸿蒙 NEXT 开发环境搭建完全指南（DevEco Studio 5.0）
发布时间：2026/7/8 6:33:17
01 鸿蒙 NEXT 开发环境搭建完全指南DevEco Studio 5.0前言工欲善其事必先利其器。在正式开发鹿鹿·笔迹心理分析这款 HarmonyOS NEXT 原生应用之前我们需要搭建一套完整的鸿蒙开发环境。本文将从DevEco Studio 的下载安装到SDK 配置、项目创建、模拟器运行手把手带你完成 HarmonyOS NEXT 开发环境的全套配置。即使你完全没有鸿蒙开发经验按照本文的步骤也能在 30 分钟内运行起第一个鸿蒙应用。系列源码仓库harmony-appGitHubHarmonyOS NEXT 官方开发指南developer.huawei.com图DevEco Studio 5.0 完整 IDE 界面包含代码编辑器、预览器、Profiler 和设备管理器一、开发环境要求1.1 硬件要求在安装 DevEco Studio 之前请确认你的开发机满足以下最低要求配置项Windows 最低要求macOS 最低要求推荐配置操作系统Windows 10/1164位macOS 13.0macOS 14 或 Windows 11内存8 GB8 GB16 GB 及以上硬盘空间30 GB 可用空间30 GB 可用空间SSD 50 GB处理器Intel i5 / AMD Ryzen 5Intel Core i5 / Apple M1M2/M3 或 Intel i7分辨率1280×8001280×8002K 及以上注意HarmonyOS 模拟器对 GPU 有一定要求建议使用独立显卡或 Apple Silicon 芯片的 Mac以获得更流畅的模拟器体验。1.2 软件依赖DevEco Studio 安装前需要先准备以下软件Node.js18.x 或 20.x LTS 版本下载地址nodejs.orgGit2.30 版本用于版本管理git-scm.comJava 运行环境DevEco Studio 内置 JDK无需单独安装二、DevEco Studio 安装2.1 下载 DevEco Studio访问 华为开发者官网 DevEco Studio 下载页选择对应操作系统的安装包.exefor Windows.dmgfor macOS当前推荐版本DevEco Studio 5.0.3 Build Version: 5.0.3.900WindowsmacOS访问华为开发者官网下载 DevEco Studio 5.0操作系统?下载 .exe 安装包下载 .dmg 安装包双击安装选择安装路径拖入 Applications 文件夹启动 DevEco Studio首次启动配置向导下载 HarmonyOS SDK配置完成创建第一个项目2.2 首次启动配置安装完成后首次启动DevEco Studio 会触发配置向导同意许可协议阅读并同意 HarmonyOS 开发者许可协议选择主题推荐选择 Dark深色主题长时间编码眼睛更舒适配置代理可选若网络访问华为服务器较慢可配置代理SDK 下载向导会自动引导你下载 HarmonyOS SDK约 2-4 GB# DevEco Studio 安装完成后的目录结构macOS/Applications/DevEco-Studio.app/ ├── Contents/ │ ├── bin/# 可执行文件│ ├── jbr/# 内置 JDKJava 17│ ├── plugins/# IDE 插件│ └── lib/# 核心库提示首次安装建议预留充足时间SDK 下载需要较稳定的网络整个配置过程约需 20-40 分钟。三、HarmonyOS SDK 配置3.1 SDK Manager 配置打开 DevEco Studio 后通过Settings → SDK Manager配置 SDKDevEco Studio Settings └── SDK Manager ├── HarmonyOS SDK Location: ~/Library/HarmonyOS/SdkmacOS 默认路径 ├── SDK Platforms │ ├── ✅ HarmonyOS 5.0.0 (API 12) — 本系列主要版本 │ └── ✅ HarmonyOS 5.0.2 (API 13) — 推荐同时安装 └── SDK Tools ├── ✅ Command Line Tools ├── ✅ Toolchains └── ✅ Emulator3.2 SDK 版本说明本系列项目使用的 SDK 版本信息如下字段值说明compatibleSdkVersion6.1.0(23)最低兼容版本API 23targetSdkVersion6.1.1(24)目标编译版本API 24runtimeOSHarmonyOS运行时操作系统arkTSVersion1.0ArkTS 语言版本{app:{products:[{name:default,runtimeOS:HarmonyOS,compatibleSdkVersion:6.1.0(23),targetSdkVersion:6.1.1(24)}]}}版本说明6.1.0(23)是 SDK 版本6.1.0与 API 级别23的组合表示法对应 HarmonyOS NEXT API 23。四、项目创建4.1 新建 HarmonyOS 项目在 DevEco Studio 欢迎界面点击Create Project在创建向导中选择以下配置配置项推荐选择说明TemplateEmpty Ability空白模板最适合从头学习Project TypeApplication标准应用非元服务/原子化服务LanguageArkTS鸿蒙原生开发语言推荐Compatible SDK6.1.0(23)本系列使用的最低 SDKModelStageStage 应用模型推荐现代化模型Bundle Namecom.xxx.xxx应用包名全局唯一标识符4.2 项目基础配置文件项目创建后有两个关键配置文件需要理解AppScope/app.json5应用级配置{app:{bundleName:com.handwriting.analysis,vendor:handwriting,versionCode:1000000,versionName:1.0.0,icon:$media:app_icon,label:$string:app_name,distributedNotificationEnabled:false}}应用级 build-profile.json5构建配置{app:{signingConfigs:[],products:[{name:default,runtimeOS:HarmonyOS,compatibleSdkVersion:6.1.0(23),arkTSVersion:1.0,targetSdkVersion:6.1.1(24)}],buildModeSet:[{name:debug},{name:release}]},modules:[{name:entry,srcPath:./entry,targets:[{name:default,applyToProducts:[default]}]}]}关键配置字段说明bundleName应用包名需在华为开发者联盟注册格式为倒置域名versionCode整数版本号如1000000 1.0.0每次发版必须递增versionName用户可见版本号字符串如1.0.0compatibleSdkVersion最低兼容 SDK决定应用支持的最老鸿蒙版本五、hvigor 构建系统5.1 hvigor 简介HarmonyOS 使用hvigor作为构建工具类似 Android 的 Gradle配置文件为hvigor/hvigor-config.json5{modelVersion:5.0.0,dependencies:{ohos/hvigor-ohos-plugin:^5.0.0}}5.2 常用构建命令# 在 DevEco Studio Terminal 中执行# 清理构建缓存hvigor clean# 构建 debug HAP 包hvigor assembleHap# 构建 release HAP 包hvigor assembleHap--moderelease# 安装到连接的设备hdc shell aa start-aEntryAbility-bcom.handwriting.analysis# 查看设备列表hdc list targetshvigor 构建的主要产物debug HAP用于调试包含调试符号无需签名release HAP用于发布需要签名证书APP Pack多个 HAP 打包后的应用包用于上架应用市场提示DevEco Studio 内集成了构建工具栏日常开发通常直接使用 IDE 的运行按钮无需手动执行 hvigor 命令。六、模拟器配置与运行6.1 创建模拟器通过Tools → Device Manager创建 HarmonyOS 模拟器点击Create virtual device选择设备类型Phone推荐 Huawei Mate 60 系列规格选择系统镜像HarmonyOS 5.0.0 (API 12)配置硬件参数RAM: 4GB存储: 8GB# 模拟器内存分配建议Phone 模拟器配置 RAM:4096MB最低推荐8192MB 内部存储:8GB 分辨率:1080×2340(FHD)像素密度:420dpi6.2 运行第一个 App完成项目创建后按以下步骤运行在 DevEco Studio 工具栏选择已创建的模拟器点击绿色▷ Run按钮或快捷键CtrlR/CmdR等待 HAP 构建和安装首次约需 1-3 分钟模拟器屏幕上将显示默认的Hello World页面运行过程中的日志查看// EntryAbility.ets 中的日志输出import{hilog}fromkit.PerformanceAnalysisKit;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(0x0000,HelloWorld,%{public}s,Ability onCreate);}}在 DevEco Studio 的HiLog窗口中可以实时查看日志输出支持按 TAG 过滤。七、真机调试配置7.1 连接真机如果需要在真实鸿蒙设备上调试需要额外配置开启开发者模式在手机设置 → 关于手机连续点击版本号 7 次启用 USB 调试开发者选项 → USB 调试连接电脑使用数据线连接设备管理器中选择通过 USB 传输文件安装签名证书在华为开发者联盟申请调试证书详见第 18 篇7.2 HDC 命令行工具HDCHarmonyOS Device Connector是华为提供的设备连接工具类似 Android 的 ADB# 查看已连接的设备hdc list targets# 安装 HAP 到设备hdc-t[device_id]install./entry/build/default/outputs/default/entry-default-signed.hap# 查看设备日志hdc-t[device_id]hilog-TAPP# 进入设备 Shellhdc-t[device_id]shell注意真机调试需要华为开发者联盟账号和调试证书新手可以先用模拟器学习待需要测试相机、NFC 等硬件功能时再切换真机。八、常见问题排查8.1 SDK 下载失败常见原因及解决方案网络超时配置 DevEco Studio 网络代理Settings → Appearance Behavior → System Settings → HTTP Proxy磁盘空间不足清理系统缓存确保至少 20 GB 可用空间权限问题macOS以管理员权限运行安装程序8.2 模拟器无法启动错误信息原因解决方案Emulator failed to start虚拟化未开启BIOS 中开启 Intel VT-x / AMD-VHAXM installation requiredHAXM 未安装SDK Manager 中安装 HAXMEmulator out of memory内存不足减少其他应用内存占用或增加模拟器 RAM8.3 构建报错 ArkTS 编译失败# 常见 ArkTS 编译错误error TS6059: File...is not underrootDir.# 解决检查 tsconfig.json 的 rootDir 配置error: Cannotreadpropertyxxxof undefined# 解决检查空值安全使用可选链 this.xxx?.yyy总结本文完整介绍了 HarmonyOS NEXT 开发环境的搭建流程环境准备硬件要求、Node.js 和 Git 安装DevEco Studio 安装下载、安装、首次配置向导SDK 配置通过 SDK Manager 安装目标 API 版本项目创建Stage 模型 ArkTS 语言 Empty Ability 模板模拟器运行创建虚拟设备运行第一个 Hello World真机调试HDC 工具、开发者模式、签名证书常见问题网络、内存、编译错误的排查方案至此你已经拥有了一套完整的鸿蒙 NEXT 开发环境可以开始探索后续的应用开发之旅。一句话记忆DevEco Studio 5.0 SDK API 14 模拟器 鸿蒙 NEXT 最小可用开发套件。确保三者版本对齐是避免 99% 初期问题的关键。下一篇预告第02篇 Stage 应用模型深入解析UIAbility 生命周期如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源HarmonyOS NEXT 官方文档DevEco Studio 下载安装Node.js 官方下载ohpm 包管理器HarmonyOS SDK 配置指南模拟器使用指南HDC 命令参考第00篇 开篇与项目总览第02篇 Stage应用模型
