要点
鸿蒙（HarmonyOS NEXT）开发环境的主体只有一个安装包：DevEco Studio。它把 IDE、HarmonyOS SDK、预览器、模拟器管理、签名工具打包在一起，国内官网直连下载，不需要配镜像、不需要代理——这是它和 Flutter、Android 生态在体验上最大的不同。装完之后真正要理解的是三件事：工程长什么样（Stage 模型、module.json5）、用哪种方式跑起来（预览器 / 模拟器 / 真机三层），以及上真机前绕不开的签名这道门。
系统要求
操作系统：DevEco Studio 官方只提供 Windows 与 macOS 两个版本，没有 Linux 版——Linux 用户需要一台 Windows/macOS 机器或虚拟机。内存 16GB 起步比较舒适（本地模拟器本身就是一个虚拟机，很吃内存），磁盘建议预留 30GB 以上（IDE + SDK + 模拟器镜像 + Gradle 级别的缓存都会占地方）。具体推荐配置以华为开发者官网《下载与安装》页的当前说明为准。
装的是什么：三件套的关系
| 组件 | 是什么 | 什么时候用 |
|---|---|---|
| HarmonyOS SDK | 对应某个 API 版本的编译工具链、ArkTS/ArkUI 声明文件与模拟器组件 | 随 IDE 首次启动下载；工程的 compileSdk 决定用哪套 |
| 预览器（Previewer） | IDE 内置的单页面 UI 渲染器 | 秒级看布局效果；不跑系统级行为（导航、权限弹窗、多数系统 API） |
| 模拟器（Emulator） | 本地或云端的完整虚拟设备 | 验证生命周期、页面跳转、权限申请这些预览器管不了的事 |
三层各司其职：写界面时预览器刷新最快；调逻辑和系统交互用模拟器；最终表现（帧率、手势、传感器）只信真机。较新版本的 DevEco Studio 在没有本地模拟器时会预置一个可快速启动的模拟器，省去手动创建。
下载与安装（国内渠道）
下载入口在华为开发者官网的 DevEco Studio 专区（developer.huawei.com，或 cn.devecostudio.huawei.com），提供 Windows（exe 安装器）与 macOS（dmg）版本。服务器在国内，直连速度正常，全程不需要配镜像环境变量——习惯 了 Flutter 折腾 PUB_HOSTED_URL 的人到这里可以松口气。注意区分 Release 与 Beta：Release 配套稳定版 SDK，Beta 用于尝鲜下一版 API，入门阶段直接下 Release。
安装后的首次启动会下载 SDK 与工具链，这一步耗时取决于网速，中断后重开 IDE 会继续。之后可以在 Settings 的 SDK 页面补装其他 API 版本的 SDK，多版本共存不是问题。
创建首个工程
File → New → Create Project → Application → Empty Ability。关键选项：
| 选项 | 填什么 | 为什么 |
|---|---|---|
| Project name / Bundle name | 项目名随意；Bundle name 是应用唯一标识（如 com.example.myapp） | Bundle name 后期改名牵扯签名与上架，起名时认真点 |
| Compile SDK | 默认当前 Release 配套的 API 版本即可 | compileSdk 高于手头设备的 API 版本时，真机跑不了 |
| Model | Stage（默认且唯一） | NEXT 不再支持旧的 FA 模型；网上 FA 模型教程全部过时 |
生成的工程目录与语义：
MyApp/
├── AppScope/
│ └── app.json5 # 应用级配置：bundleName、版本号、应用图标
├── entry/ # 主模块，打包成一个 HAP（应用安装单元）
│ ├── src/main/
│ │ ├── ets/ # ArkTS 源码
│ │ │ ├── entryability/EntryAbility.ets # UIAbility 入口（应用生命周期）
│ │ │ └── pages/Index.ets # 首页页面
│ │ ├── resources/ # 字符串/图片等资源，按 base、zh_CN 等限定词目录分组
│ │ └── module.json5 # 模块清单：权限声明、Ability 注册、设备类型
│ ├── oh-package.json5 # 模块依赖清单（相当于 npm 的 package.json）
│ └── build-profile.json5 # 模块构建配置
├── build-profile.json5 # 工程级构建配置：签名、SDK 版本
├── hvigorfile.ts # hvigor 构建脚本入口（鸿蒙自己的构建工具）
└── oh-package.json5 # 工程级依赖日常开发 90% 的时间在 entry/src/main/ets 里；module.json5 是权限和网络配置的落点，后面网络一节会反复用到它。构建体系叫 hvigor，角色等同 Web 侧的 webpack/vite、Android 侧的 Gradle，但配置默认够用，入门阶段不用碰。
三种运行方式
| 方式 | 启动速度 | 覆盖能力 | 典型问题 |
|---|---|---|---|
| 预览器 | 最快，保存即刷新 | 单页面 UI 布局 | 用到部分系统 API 时白屏或提示不支持 |
| 模拟器 | 慢（要开机） | 接近完整系统 | 吃内存；老机器可能起不来 |
| 真机 | 中 | 完全真实环境 | 必须先配签名 |
签名与真机调试
HarmonyOS NEXT 强制应用签名：没有签名的 HAP 包（Harmony Ability Package，应用安装单元）装不进任何设备，这是和”浏览器里就能跑”的 Web 开发最大的观念差异。调试签名由三件套组成：密钥库（.p12，本地保存私钥）、证书（.cer）与调试 Profile（.p7b，绑定开发者账号与设备）。
入门用自动签名就够：File → Project Structure → Signing Configs，勾选 Automatically generate signature，登录华为账号（需实名认证），IDE 自动生成证书、注册当前连接的设备并完成配置。手动签名（本地生成密钥和 CSR，到 AppGallery Connect 申请证书与 Profile）留给团队共享证书、CI 构建这类场景。
真机侧的准备：手机上”设置 → 关于本机”，连点”软件版本号”开启开发者模式，再在”开发者选项”里打开 USB 调试，数据线连接后选择传输文件模式。IDE 的设备列表里出现手机即可一键运行。命令行可用 hdc（HarmonyOS Device Connector，随 SDK 安装）确认设备：hdc list targets。
版本线速览
鸿蒙的版本线以 API 版本为轴，NEXT 前后是两个时代，先给一张速览表避免被旧教程绕晕：
| 时间 | 系统 / SDK | API 版本 | 备注 |
|---|---|---|---|
| 2023 及更早 | HarmonyOS 3/4 | API 9 及更早 | 兼容 Android 应用，FA 与 Stage 模型并存；大量旧教程来自这个时代 |
| 2024 上半年 | HarmonyOS 4.x / NEXT 预览版 | API 10 / 11 | API 10 配套 HarmonyOS 4.x；API 11 起转向 NEXT 开发者预览，不再兼容 Android 应用 |
| 2024-10-22 | HarmonyOS NEXT 5.0 | API 12 | NEXT 正式商用，不再兼容 Android 应用；DevEco Studio 5.0 同线配套 |
API 版本与 NEXT 版本的对应关系以 API 12 为当前线：自 2024-11 起，应用市场仅允许集成 Release SDK（API 12）的应用上架，后续 API 演进以华为官方发布为准。看旧教程先对 API 版本：API 12 之前的教程（尤其 FA 模型时代）与 DevEco Studio 5.0 的截图、菜单和报错信息对不上。具体每个版本的变化以官网 Release Notes 为准。
常见问题
Q1: 首次启动 SDK 下载失败或极慢
官网在国内一般不慢；失败多为网络切换或代理干扰。重开 IDE 让下载续传；实在不行到 Settings → SDK 里手动触发补装。不要去第三方网盘下 SDK 离线包，版本对不上是自找麻烦。
Q2: 本地模拟器创建失败或启动黑屏
优先查两点：BIOS 里的 CPU 虚拟化是否开启（Windows 还需确认 Hyper-V/虚拟机平台状态），以及空闲内存是否够（8GB 是底线）。老机器跑不动本地模拟器时，用云端远程模拟器替代。
Q3: 自动签名失败
按顺序排查：账号是否完成实名认证；调试证书额度是否用完（每个华为账号最多申请 2 个调试证书，之前手动签过名就可能占满）；AGC 上是否已有项目。额度满时需要到 AppGallery Connect 删掉不用的旧证书再试。
Q4: 预览器白屏
预览器只渲染 UI，页面里若调用了它不支持的系统 API（典型如 http 网络请求）就会白屏或报”暂不支持预览”。这不是代码 bug，换模拟器或真机验证。
最佳实践与反模式
反模式一：跳过 DevEco Studio，用 VS Code 手搭工具链。官方的模拟器管理、自动签名、预览器、ArkTS 严格语法检查都深度集成在 DevEco Studio 里，VS Code 没有对等插件，纯手工链路对新手是负优化。
反模式二：IDE、SDK、真机系统三方版本错配。compileSdk 选了 Beta 版 SDK，手头真机还是 NEXT 5.0 Release（API 12），装包必失败。先看设备系统版本，再定工程的 compileSdk。
反模式三：拿 API 12 之前、FA 模型时代的旧教程对照现在。那个年代的配置文件叫 config.json，现在是 module.json5；目录结构和 API 也都对不上。看到 config.json 直接关掉那篇教程。
检查清单
- DevEco Studio（Release 版）安装完成，首次启动 SDK 下载成功
- Empty Ability 工程创建成功，预览器能看到 Index 页面
- 本地或远程模拟器能启动并运行工程
- 自动签名配置完成，真机出现在设备列表并可运行
- 知道自己的 compileSdk 对应哪个 API 版本，且不高于真机系统
下一步
这篇的产出是一台能创建、能预览、能上真机的开发机。下一篇《第一个鸿蒙应用》在 Empty Ability 模板之上写一个计数器与待办应用，讲清 ArkUI 声明式范式。想横向对比工具链设计的读者，可以看《Flutter 环境搭建与工具链》（SDK 为中心 + 镜像变量的折腾）和《Vue 3 环境搭建与工具链》（包管理器为中心），三套生态一对比，”一站式 IDE”的取舍就清楚了。
版本核实（撰写时检索，2024-12）：HarmonyOS NEXT 5.0 已于 2024-10-22 正式发布（API 12），DevEco Studio 当前 Release 为 5.0 线（5.0.0/5.0.1，配套 HarmonyOS SDK API 12）；NEXT 仅支持 Stage 模型、不再兼容 Android 应用；NEXT 强制应用签名、每个账号至多 2 个调试证书。IDE 界面路径与各版本细节可能随版本调整，以 developer.huawei.com 的官方文档与 Release Notes 为准。