第 2 节：搭建 DevEco Studio 开发环境

学习目标

• 在自己的电脑上装好 DevEco Studio 26.0.0 和 API 20（HarmonyOS 6）SDK。
• 看懂 Empty Ability 工程的目录结构，知道业务代码、模块清单、全局配置分别在哪。
• 打开自动签名、创建模拟器，具备「点 Run 就能出包」的环境。
• 提前避开虚拟化、代理、路径中文这几个新手必踩的坑。

一、引入：环境通不通，决定你能不能跑通第一段代码

上一节我们知道了要为纯血鸿蒙写 ArkTS 应用。这一节的目标只有一个：在电脑上把 DevEco Studio 装好，做到「选个模拟器、点 Run、屏幕上出现应用」。整个过程不涉及复杂配置，但每个环节都有几个新手必踩的坑，这一节逐个标出来。

二、核心概念与正文

2.1 DevEco Studio 是什么

DevEco Studio 是华为官方的鸿蒙应用 IDE，基于 IntelliJ IDEA 社区版定制。本小册基线为 DevEco Studio 26.0.0 Release，内置 JDK、Node、Hvigor、ohpm。它和 Android Studio、VS Code 的区别：

• 开箱即用：SDK、模拟器、签名、预览器全部集成，不用单独配 SDK Manager；
• 带 ArkUI 预览器：改一行 build()，右边即时看到 UI，不用每次跑模拟器；
• 内置本地模拟器：支持手机、平板、2-in-1、折叠屏多种形态；
• 支持命令行构建：CI 场景用 hvigorw，不依赖 IDE。

下载入口在华为开发者官网，注册一个免费华为开发者账号即可下载。学习和工作用 Release 版，不要追 Beta——Beta 经常有工具链 bug。建议关掉自动更新，需要升级时手动下载新安装包覆盖安装。

2.2 机器要求与安装要点

DevEco 本身不挑系统，但模拟器要吃内存：

项目	Windows	macOS
系统版本	Windows 10 64 位（1909+）或 Windows 11	macOS 12+（支持 Intel 与 Apple Silicon）
CPU	x86_64，开启虚拟化（VT-x）	Apple Silicon（arm64）或 Intel
内存	16 GB 起步，建议 32 GB	16 GB 起步，建议 24 GB+
磁盘	至少 20 GB 空闲，建议 SSD	同左

安装步骤很常规：下载对应平台安装包 → 双击安装 → 第一次启动自动下载 SDK（约 8–10 GB）。安装路径不要带中文和空格，这是老坑。

2.3 SDK 与命令行工具

首次启动引导你装 SDK，本小册基线是 API 20（对应 HarmonyOS 6 / OpenHarmony 6.0 Release），新建工程时 compileSdk 选 26（年份制版本号，对应 API 20）。SDK Manager 在菜单 Tools → SDK Manager：至少勾一个 HarmonyOS 6 / API 20，SDK Tools 默认全选。

日常用得最多的命令行工具是 hdc（鸿蒙设备桥接，类似 adb）：

# 查看已连接设备
hdc list targets

# 安装 hap 到设备
hdc install entry-default-signed.hap

# 进入设备 shell
hdc shell

# 拉日志（过滤 Ability 相关）
hdc hilog | grep -i "EntryAbility"

工程根目录下还有 hvigorw（Windows 是 hvigorw.bat）：./hvigorw assembleHap 就能打 hap 包，CI 和排查构建问题时比点 IDE 按钮有用。SDK 默认位置：Windows 在 C:\Users\<用户名>\AppData\Local\Huawei\Sdk，macOS 在 ~/Library/Huawei/Sdk，这个路径写进工程根目录的 local.properties，不要随便移动。

2.4 工程目录结构：新手最容易迷路的地方

Empty Ability 模板长这样，记住三个关键位置：AppScope 是全局、entry/src/main/ets 是业务代码、module.json5 是模块清单。

HelloWorld/
├── AppScope/                  # 应用级全局信息
│   ├── app.json5              #   包名、版本号、允许的设备类型
│   └── resources/base/       #   应用级图标、名称（所有 Ability 共享）
├── entry/                     # 一个 HAP 模块（主入口模块）
│   └── src/main/
│       ├── ets/              # ArkTS 源码
│       │   ├── entryability/EntryAbility.ets   # UIAbility 入口
│       │   └── pages/Index.ets                # 首页
│       ├── resources/base/   # 模块级资源（字符串、颜色、图标）
│       └── module.json5      # 模块配置：Ability 声明、权限、入口
├── oh_modules/                # ohpm 依赖缓存（类似 node_modules，别手改）
├── build/                     # 构建产物（自动生成，不提交 git）
├── build-profile.json5        # 工程级构建配置：SDK 版本、签名、产品
├── hvigorfile.ts              # 构建脚本入口
├── oh-package.json5           # 工程级依赖声明（类似 package.json）
└── local.properties           # 本地 SDK 路径（机器相关，不提交）

应用级配置长这样：

{
  "app": {
    "bundleName": "com.example.helloworld",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

模块清单 module.json5 决定系统怎么启动你的应用，关键是 skills 里的 entity.system.home——它告诉系统「这个 Ability 是桌面图标点击后要启动的入口」，少了它 App 装上去桌面看不到图标：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet"],
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}

2.5 模拟器、真机与自动签名

创建模拟器：Tools → Device Manager → Create，选设备形态（Phone/Tablet/Foldable/2-in-1），选 API 20 镜像，等镜像下载完。第一次启动慢（1–2 分钟），之后热启动很快。每个镜像约 3–5 GB，多建几个很快占满磁盘，不用的及时删；要恢复出厂选 Wipe Data。模拟器卡的话，在 Edit 里把内存从默认 2 GB 调到 4 GB。

真机调试（性能、网络、传感器更真实）：设置 → 关于手机 → 连续点 7 次「版本号」开启开发者模式 → 开发者选项打开 USB 调试 → 数据线连电脑 → 手机弹窗点「允许此设备调试」。连不上先换一根能传数据的线（很多充电线是坏的）。

自动签名：装到真机/模拟器都要签名，DevEco 对开发者账号做了自动签名，99% 的情况不用手动做 CSR、.p12、.cer：

1. File → Project Structure → Signing Configs；
2. 勾选 Automatically generate signature；
3. 登录华为开发者账号；
4. 等状态变成 Signing succeeded。

三、完整示例：环境自检清单

按下面顺序走一遍，全绿就说明环境通了：

# 1. 确认命令行可用（IDE 底部 Terminal 已配好环境变量）
hdc list targets          # 至少能看到一个模拟器/真机
ohpm -V                   # 能打印 ohpm 版本

# 2. 命令行出包（在工程根目录）
./hvigorw assembleHap     # Windows 用 hvigorw.bat
# 成功后产物在 entry/build/default/outputs/default/ 下

再配合三个 DevEco 专属高频动作，效率会高很多：

• Previewer 实时预览：打开任意 .ets 页面，右侧边栏点 Previewer，改 build() 保存后自动刷新，调样式时强烈推荐；
• Structure 结构面板：左下角以树状列出组件层级，布局错乱时一眼看出哪层嵌套错了；
• 底部 Terminal：已配好环境变量，直接输 hdc、ohpm 就能用。

遇到报错先看两个地方：底部 Build 窗口的构建日志（往上翻第一条 ERROR，90% 的问题都在那），和 Log 窗口的 hilog。

四、踩坑提示

⚠️ 坑 1：模拟器起不来。 Windows 必须在 BIOS 里开启 CPU 虚拟化（Intel VT-x / AMD-V）。任务管理器 → 性能 → CPU 右下角看「虚拟化：已启用」，显示「已禁用」就重启进 BIOS 打开。

⚠️ 坑 2：首次下载 SDK 卡在 40%。 公司网络开了代理或抓包时常见。临时关代理，或把 HTTP 代理配成「自动检测」；不要把代理指向抓包工具，SDK 证书校验会失败。

⚠️ 坑 3：自动签名失败。 最常见原因是 bundleName 和你账号下已注册的包名撞了，或网络没登进 AGC。换个反向域名（把 com.example 改成自己的域名）通常就好。

⚠️ 坑 4：搞混两套 resources。 AppScope/resources 是整个应用共享的（图标、名称），entry/src/main/resources 是这个 HAP 自己的。多模块工程里这层差别会非常明显。

五、小结

• 装 DevEco 26.0.0 Release → 装 API 20 SDK → New Project 选 Empty Ability（Stage 模型）→ 打开自动签名 → 选模拟器 Run。
• 目录三要素：AppScope 全局、entry/src/main/ets 业务代码、module.json5 模块清单。
• 记住一个命令 hdc list targets 验证设备连接，一个命令 ./hvigorw assembleHap 命令行出包。
• 三大坑：虚拟化没开、代理抓包拦 SDK、路径带中文/空格。

六、思考题 / 实践任务

• 动手任务：新建一个 HelloWorld 工程，把 bundleName 改成你自己的反向域名，跑通自动签名，并用 hdc list targets 确认设备在线。
• 动手任务：在 Device Manager 里建一个折叠屏模拟器，分别在折叠/展开状态下看预览效果，为后面的多端适配建立直观感受。

环境装好了，但工程还是模板那行默认的「Hello World」。下一篇我们正式写第一段 ArkTS 界面，亲手改文字、加按钮，让它在模拟器上跑起来——你会第一次真正体会到「状态一变，界面自动刷新」是什么感觉。