我先核实一下当前 DevEco Studio 的最新版本、macOS 系统要求和鸿蒙 SDK 现状，避免给出过时的安装步骤。

我再确认一下当前最新正式版本号和 macOS 上的模拟器/真机调试细节。

核实完成。当前鸿蒙开发套件已进入 ‌26.0.0 Release 时代‌（2026 年 8 月 29 日发布，配套 DevEco Studio 26.0.0.821），且从 API 26.0.0 起‌版本号格式从 X.Y.Z(N) 统一改为语义化 X.Y.Z‌。下面是 macOS 上从零到跑通第一个应用的完整流程。

DevEco Studio 环境搭建，鸿蒙开发入门第一步（macOS 版）

一句话前提‌：DevEco Studio 已经把 HarmonyOS SDK、Node.js、Hvigor、OHPM、模拟器‌全部打包在一起‌了，是真正的开箱即用——‌你不需要单独装 JDK、不需要单独配 SDK、不需要装 Node‌。macOS 上真正会卡住新手的，只有三件事：‌下载时选错芯片架构‌、‌被 Gatekeeper 拦下打不开‌、‌真机连不上‌。这篇就围绕这三件事展开。

一、先明确：你要装哪个版本

macOS 上搭环境前，先搞清楚版本配套关系，否则后面会到处对不上号。

表格

版本 API 发布时间 建议

26.0.0 Release‌（26.0.0.821） API 26.0.0 2026/08/29 ‌最新正式版‌，新工程首选

6.1.1 Release‌（6.1.1.300） 6.1.1(24) 2026/07/29 设备存量最大，真机调试最稳

6.1.0 Release 6.1.0(23) 2026/04/20 偏旧，新项目不建议

怎么选‌：

纯粹入门学习、跑模拟器‌ → 直接装最新的 ‌26.0.0 Release‌。

要连自己的手机调试‌ → 先按下面命令查一下手机的 API 版本，再决定。目前存量设备里 ‌6.1.1(24) 占比约 84.93%‌，是最主流的；而 26.0.0 的测试版设备占比只有 4.65%。‌如果你的手机还是 6.1.1，用 6.1.1 Release 少踩坑。‌

⚠️ ‌版本号格式变了‌：API 26.0.0 之前的写法是 6.1.1(24)，括号里的数字是 OpenHarmony 底座 API level；从 26.0.0 起统一改成 26.0.0 这种语义化格式。看到两种写法不要以为是不同产品。

二、第一步：macOS 环境自检

官方要求如下（这是‌官方口径‌，不是网上传的）：

表格

项目 官方要求

操作系统 Intel Mac：‌macOS 11/12/13/14/15/26‌；Apple Silicon：‌macOS 12/13/14/15/26‌

内存 ‌8GB 及以上‌

硬盘 ‌100GB 及以上‌

分辨率 1280×800 像素及以上

打开终端，跑这三条命令自检‌：

bash

# 1. 看系统版本（关键：确认 ≥ 官方下限）

sw_vers

# 2. 看芯片架构（决定你下哪个安装包！）

uname -m

# 输出 arm64 → Apple Silicon（M1/M2/M3/M4），下 Mac(ARM) 版

# 输出 x86_64 → Intel 芯片，下 Mac(x86) 版

# 3. 看磁盘可用空间（要 ≥100GB）

df -h /

两个必须记住的现实差异‌：

Intel Mac 最低支持到 macOS 11，Apple Silicon 最低 macOS 12‌。M 系列芯片的机器跑不了 macOS 11，别硬试。

官方写 8GB 内存"可运行"，但‌实际开发体验很差‌。你同时开 IDE + 模拟器 + 浏览器，16GB 才算够用，32GB 才舒服。‌能升内存就升，这是唯一一个后期补不回来的硬指标。‌

💡 ‌路径铁律‌：从这一步起，‌所有涉及路径的地方（安装位置、SDK 位置、工程位置）都不要出现中文和空格‌。DevEco Studio 对路径里的中文字符支持很差，会在编译阶段抛出莫名其妙的文件访问异常。

三、第二步：下载安装包（这里最容易踩坑）

下载地址

唯一官方渠道：‌华为开发者联盟官网的 DevEco Studio 下载页‌（developer.huawei.com → 开发者 → 工具 → DevEco Studio）。‌需要登录华为账号‌（没有就先注册一个，后面申请调试证书也用它）。

🔴 最大的坑：选错芯片架构

下载页会并列给出多个包，‌这是新手第一个翻车点‌：

表格

安装包标识 对应机器

Mac (ARM)‌ M1 / M2 / M3 / M4 等 Apple Silicon

Mac (x86)‌ 老的 Intel 芯片 Mac

Windows (64-bit) 与你无关

为什么致命‌：‌选错了安装过程通常不报错，但启动阶段会莫名其妙崩溃或卡死‌——因为 Intel 版在 M 系列上要走 Rosetta 转译，性能和稳定性都很糟。原生 ARM 版相比 Rosetta 转译模式，项目初始化、代码索引、模拟器启动都有显著提速。

对着 uname -m 的结果选，别凭感觉。‌

下载后必做：完整性校验

下载页会给出工具完整性校验的 SHA-256 值。‌一定要校一遍‌，安装包动辄 2GB 以上，网络抖动导致的损坏很难在安装时发现：

bash

# 把 <下载路径> 和 <官网给的SHA256值> 替换成实际内容

shasum -a 256 ~/Downloads/deveco-studio-*.dmg

对得上再安装。

四、第三步：安装 + 解决"打不开"问题

macOS 下的安装‌只有一步‌：

双击 .dmg 文件挂载磁盘映像；

把 ‌DevEco-Studio.app 拖进 Applications 文件夹‌；

等复制完成（几分钟，看磁盘速度），弹出映像。

🔴 必然遇到的拦截：Gatekeeper

首次启动，macOS 几乎一定会弹窗拦截：

"无法打开，因为 Apple 无法检查其是否包含恶意软件"‌ 或 ‌"已损坏"‌

正确处理姿势‌（不要去找什么破解脚本）：

打开 ‌系统设置 → 隐私与安全性‌；

往下拉到"安全性"区域，会看到一条关于 DevEco Studio 的提示；

点 ‌"仍要打开"‌，再确认一次打开。

之后就能正常启动了。这是 macOS 对第三方开发工具的标准待遇，‌不是安装包有问题‌。

五、第四步：首次启动配置（三分钟搞定）

1. 导入设置

弹出 Import DevEco Studio Settings 时，‌选 Do not import settings，点 OK‌。新手直接跳过，别导入旧配置。

2. 同意协议

阅读并勾选用户协议，一路 Next。

3. 确认 SDK —— 这里是好消息

HarmonyOS SDK 已内置在 DevEco Studio 里，安装 IDE 时自动装好配套版本，无需任何额外配置。‌

位置：DevEco Studio 安装位置下的 ‌sdk‌ 目录；

查版本：菜单栏 ‌Help > About HarmonyOS SDK‌。

只有做 ‌OpenHarmony‌（开源鸿蒙）应用开发时，才需要额外去 DevEco Studio > Preferences/Settings > OpenHarmony SDK 手动下载。

4. 切换成中文界面（可选）

从 ‌6.0.0 Beta1 起，中文化插件已默认内置启用‌。要切换：

DevEco Studio > Preferences/Settings → Appearance & Behavior > System Settings > Language‌ → 选 ‌Chinese (Simplified)‌ → Apply → 弹窗点 Restart。

注意：‌6.1.0 Beta1 起选项名从 Chinese 变成了 Chinese(Simplified)‌。如果列表里找不到，说明你用的是更老的版本，需要先去 Plugins 手动启用语言插件。

六、第五步：跑一次环境诊断（强烈建议）

这是很多人跳过、但最省时间的一步。‌

欢迎页‌：直接点 ‌Diagnose‌；

工程内‌：菜单栏 ‌Help > Diagnostic Tools > Diagnose Development Environment‌。

诊断会检查‌电脑配置、网络连通性、依赖工具是否安装‌。任何一项显示未通过，界面上会给出‌具体的修复建议‌——照着修，比事后对着报错瞎猜强得多。

七、第六步：创建并运行第一个工程

1. 新建工程

File > New > Create Project，模板选 ‌Empty Ability‌，配置：

表格

配置项 建议值

Project name‌ HelloWorld（纯英文，无空格）

Bundle name‌ com.example.helloworld

Save location‌ 纯英文路径，‌不要放桌面或含中文的目录‌

Language‌ ‌ArkTS‌（鸿蒙主力语言，新手就学这个）

Compatible SDK‌ 跟上一步选的 DevEco 版本配套

工程初始化时 IDE 会做代码索引，‌首次会慢一些，属正常现象‌。

2. 认识工程结构

text

HelloWorld/

├── AppScope/                      # 应用全局资源

│   ├── app.json5                  # 应用级配置（包名、版本、图标）

│   └── resources/

├── entry/                         # 主模块（可多个）

│   ├── src/main/

│   │   ├── ets/

│   │   │   ├── entryability/      # 应用入口 Ability

│   │   │   └── pages/Index.ets    # ← 你改的第一个文件在这

│   │   ├── resources/             # 模块资源（图片、字符串、颜色）

│   │   └── module.json5           # 模块配置

│   └── build-profile.json5

├── build-profile.json5            # 工程级构建配置

├── hvigorfile.ts                  # 构建脚本

└── oh-package.json5               # 依赖管理（类似 package.json）

3. 看你的第一段 ArkTS 代码

打开 entry/src/main/ets/pages/Index.ets，会看到类似结构：

typescript

@Entry

@Component

struct Index {

  @State message: string = 'Hello World';

  build() {

    Row() {

      Column() {

        Text(this.message)

          .fontSize(50)

          .fontWeight(FontWeight.Bold)

      }

      .width('100%')

    }

    .height('100%')

  }

}

看懂三个关键点就够了‌：

@Entry‌：标记这是页面入口；

@Component‌：声明这是自定义组件；

@State‌：状态变量，‌改了它，界面会自动重绘‌——这就是声明式 UI 的核心。

把 'Hello World' 改成任意中文，保存，界面会实时更新。

4. 运行 — 先用预览器，再上模拟器

最快的方式：预览器（Previewer）‌

点编辑器右上角的 ‌Previewer‌ 图标，无需启动模拟器，秒级看到界面效果。‌改代码即时刷新，是调 UI 最高效的方式。‌

完整的方式：模拟器（Emulator）‌

点顶部设备下拉框，选模拟器设备，然后运行。

macOS 运行快捷键要注意‌：

运行应用：‌Control + R‌（不是 Cmd+R，这是 Mac 版鸿蒙插件的键位）

调试应用：‌Control + D‌

八、第七步：真机调试（想上真实手机才需要）

前置：手机侧准备

手机系统版本需 ‌HarmonyOS NEXT Developer Beta1 或以上‌；

打开开发者选项：‌设置 > 具体设备名称 → 连续点击「软件版本」7 次‌ → 提示"开启开发者选项" → 确认 → 输入 PIN 码 → ‌设备自动重启‌；

重启后，‌设置 > 系统 > 开发者选项‌ 里就有了相关开关。

方式一：USB 连接（最常用）

用 USB 线连接 Mac 和手机；

在 ‌设置 > 系统 > 开发者选项‌ 中打开 ‌USB 调试‌；

手机上会弹"允许 USB 调试"框，点「允许」‌（这一步最容易漏！）；

点运行，DevEco Studio 会自动编译、签名、安装、启动。

⚠️ ‌必须先配置调试签名‌（File > Project Structure > Signing Configs 里勾选自动签名），否则装不上。这个签名需要登录华为账号，也是前面让你注册账号的原因。

方式二：无线连接（免线缆）

手机和 Mac 连‌同一个 WLAN‌；

手机 ‌开发者选项‌ 里打开 ‌无线调试‌，‌记下 IP 地址和端口号‌；

在 DevEco Studio 里：

6.1.1 Release（6.1.1.300）及以上‌：菜单栏 ‌Tools > IP Connection‌，按 IP:port 格式填写，点 Connect。连接成功后会‌默认开启屏幕常亮‌（IDE 会持续发亮屏指令，这是正常行为，不需要可在面板里 Disable Screen Always-On 关闭）；

更早版本‌：同样在 Tools > IP Connection 里填 IP 和端口，连接成功后设备状态显示 online。

也可以用命令行连：

bash

hdc tconn 设备IP地址:端口号

🔴 连不上怎么办：用「设备连接助手」

从 ‌5.1.1 Beta1 起‌，DevEco Studio 内置了排查工具。‌设备下拉框显示 No Devices 时‌：

点击设备下拉框 → ‌Troubleshoot Device Connections‌，它会带你分三步走：

通过 USB 连接设备‌：按提示连好后点 Rescan Devices，确认扫描结果里有你的设备；

启用 USB 调试‌：核对系统版本、开发者选项、USB 调试开关；

重启 HDC 服务‌：still 识别不到，点 Restart hdc Service。

同时检查 macOS 侧的权限‌：到 ‌系统设置 → 隐私与安全性 → 文件和文件夹‌，确保给 DevEco Studio 授予了‌完全磁盘访问权限‌。这是 Mac 特有的坑，Windows 上不存在。

九、macOS 专属避坑清单（照这十条对一遍）

架构选错‌：下载前必须 uname -m 确认，M 系列选 ARM，Intel 选 x86。

Gatekeeper 拦截‌：走"系统设置 → 隐私与安全性 → 仍要打开"，不要找破解方案。

路径含中文/空格‌：安装位置、SDK 位置、工程位置全部避开，这是编译异常的常见来源。

磁盘不足‌：官方要 100GB，实际算上 SDK + 模拟器镜像 + 缓存，‌SSD 更佳，机械硬盘会明显卡‌。

内存不够‌：8GB 只是能跑，‌16GB 起步‌，否则模拟器一开就卡。

首次索引慢‌：正常，等它跑完，别中途杀掉进程。

快捷键不对‌：Mac 上是 ‌Control+R 运行‌、Control+D 调试，不是 Cmd。

中文界面找不到选项‌：6.1.0 Beta1 起叫 Chinese(Simplified)，老版本需先启用插件。

真机 USB 不弹授权框‌：换 USB-C to USB-C 直连（避免 Hub/转接头），再重新插拔。

版本配套对不上‌：DevEco Studio 版本、HarmonyOS SDK 版本、手机 API 版本三者要配套，用 Help > About DevEco Studio 和 Help > About HarmonyOS SDK 逐一核对。

十、可选：把命令行工具加进 PATH

IDE 里用不需要配环境变量（DevEco Studio 5.0+ 已自动处理）。但如果你想‌在终端里直接用 hdc / ohpm / hvigorw‌，先找到它们在哪：

bash

find "/Applications/DevEco Studio.app" -name "hdc" -o -name "ohpm" -o -name "hvigorw" 2>/dev/null

拿到路径后（通常在 app 包内的 SDK toolchains 目录下），追加到 ~/.zshrc：

bash

# 把 <工具实际目录> 替换成上面 find 出来的路径

export PATH="$PATH:<工具实际目录>"

保存后执行 source ~/.zshrc，再验证：

bash

hdc -v        # 能打印版本号就说明配好了

macOS 默认 shell 从 Catalina 起就是 ‌zsh‌，配置文件是 ~/.zshrc（不是 .bash_profile），改错文件是新手常见失误。

收尾：整个流程浓缩成七步

text

1. 自检     → sw_vers / uname -m / df -h

2. 下载     → 官网 → 按芯片架构选包 → 校验 SHA-256

3. 安装     → 拖进 Applications → 隐私与安全性里"仍要打开"

4. 首启     → Do not import settings → 同意协议 →（可选）切中文

5. 诊断     → 欢迎页 Diagnose，逐项修复

6. 建工程   → Empty Ability + ArkTS → 预览器看效果 → Control+R 跑模拟器

7. 真机     → 开发者选项 → USB调试/无线调试 → 配签名 → 连不上用连接助手

只要你没在第一步选错芯片架构、没被 Gatekeeper 卡住，剩下的基本都是一路回车。‌ 真正耗时间的从来不是安装，而是被这两件事拦住。

需要我把这份指南整理成一份‌可随时翻阅的 Markdown 文档‌，或者补一份 ‌ArkTS 入门速查（声明式 UI + 状态管理 + 常见组件）‌ 接着往下走吗？告诉我你的 Mac 是什么芯片、macOS 什么版本、手机是什么 API 版本，我可以给你精确到具体下载包和版本的推荐。