1. 学习目标

完成本章学习后，你应当能够：

1. 了解鸿蒙硬件开发环境的组成。
2. 根据工具链要求检查计算机处理器、内存、磁盘和网络条件。
3. 选择适合课程和项目的操作系统环境。
4. 安装 DevEco Studio 和相关依赖。
5. 理解 JDK 版本兼容性的重要性。
6. 使用 SDK Manager 安装和管理 SDK、构建工具及设备镜像。
7. 安装和检查 USB 驱动，连接鸿蒙设备进行调试。
8. 使用鸿蒙模拟器完成没有实体设备时的开发验证。
9. 理解项目编译、构建和打包的基本过程。
10. 通过模拟器或真机安装并运行应用。
11. 根据日志和现象排查环境、连接、构建和部署问题。
12. 形成实践验证、规范操作、数据安全和工程责任意识。
13. 能够编写环境安装记录、测试报告和问题复盘文档。

2.鸿蒙硬件开发环境的组成

一个可用的开发环境不是只安装一个 IDE，而是多个层次共同组成：

计算机硬件
   ↓
操作系统
   ↓
JDK、Node.js 等基础运行环境
   ↓
DevEco Studio
   ↓
HarmonyOS SDK 与构建工具
   ↓
模拟器或实体设备
   ↓
编译、安装、调试和日志工具

1. 计算机硬件
   硬件主要影响：
   • IDE 启动速度；
   • SDK 下载和解压速度；
   • 工程索引速度；
   • 编译时间；
   • 模拟器运行流畅度；
   • 并行运行工具的数量。
2. 操作系统
   操作系统负责提供：
   • 文件系统；
   • 进程和内存管理；
   • 网络；
   • USB 设备识别；
   • 图形界面；
   • 权限管理；
   • 开发工具运行环境。
3. DevEco Studio
   DevEco Studio 是鸿蒙应用和设备开发的集成开发环境，类似于其他移动平台的官方 IDE。它通常提供：
   • 工程创建；
   • 代码编辑；
   • ArkTS/其他工程语言支持；
   • UI 预览；
   • 编译和构建；
   • 模拟器管理；
   • 真机调试；
   • 日志查看；
   • SDK 管理。
4. SDK 和工具链
   SDK 提供：
   • 系统 API；
   • 编译器；
   • 构建工具；
   • 设备调试工具；
   • 模拟器镜像；
   • 平台类型定义；
   • 示例和模板。
5. 设备或模拟器
   • 实体设备：验证真实硬件、屏幕、传感器和系统行为。
   • 模拟器：没有实体设备时进行页面、逻辑和基础功能测试。
   模拟器不能完全代替真机，尤其不能完整模拟所有硬件性能、传感器、功耗和网络环境。

3.硬件要求检查

3.1 为什么要检查硬件

开发环境中最消耗资源的通常是：
• DevEco Studio 索引；
• SDK 下载和解压；
• 编译工具；
• 模拟器；
• 日志和调试工具；
• 浏览器、文档和其他开发软件并行运行。
如果硬件不足，可能出现：
• IDE 卡顿；
• 编译时间过长；
• 模拟器启动失败；
• 磁盘空间不足；
• 系统频繁交换内存；
• 多任务时设备发热或无响应。

3.2 检查项目

1. 处理器
   处理器影响：
   • 编译速度；
   • 模拟器运行；
   • 多任务并发；
   • 大型工程索引。
   建议使用当前 DevEco Studio 和模拟器要求范围内的现代处理器。具体最低型号和指令集应查看当前官方安装要求，不要直接套用旧教程的配置。
2. 内存
   内存需要同时容纳：
   • 操作系统；
   • DevEco Studio；
   • 编译进程；
   • 模拟器；
   • 浏览器和文档；
   • 其他依赖工具。
   如果只做静态代码编辑，内存需求较低；如果运行模拟器并进行大型工程编译，需要预留更多空间。
3. 磁盘
   需要为以下内容预留空间：

DevEco Studio
HarmonyOS SDK
构建工具
模拟器系统镜像
项目源码
编译缓存
日志和测试产物

建议：
• SDK 和项目放在空间充足的磁盘；
• 不要把磁盘使用率长期维持在接近满载；
• 定期清理明确的构建缓存；
• 不要删除仍在使用的 SDK 目录。
4. 网络
网络用于：
• 下载 IDE 和 SDK；
• 安装依赖；
• 同步云端资源；
• 更新工具；
• 访问开发文档；
• 连接测试服务。
网络不稳定时，应记录失败时间、错误信息和下载阶段，不要反复盲目重试。

3.3 硬件检查清单

3.4 资源不足时的策略
• 优先使用预览器，减少模拟器占用；
• 关闭暂时不用的程序；
• 选择轻量测试设备；
• 减少同时运行的模拟器数量；
• 使用实体设备进行部分测试；
• 将 SDK 和工程放到速度较快的磁盘；
• 避免反复删除和重新下载大型镜像。

4.操作系统支持与准备

4.1 支持的操作系统

课程材料提到鸿蒙开发环境可涉及：
• Ubuntu；
• CentOS；
• Windows；
• 以及课程要求中提到的 macOS 等环境。
不同版本的 DevEco Studio、SDK 和模拟器对操作系统的支持范围可能不同。选择系统时必须以当前版本的官方要求为准。

4.2 Windows 环境准备

检查：
• 系统版本和补丁；
• 用户安装权限；
• 防火墙和安全软件；
• USB 驱动安装能力；
• 环境变量；
• 路径长度；
• 虚拟化和图形加速设置。
建议使用简洁的项目路径：

D:\HarmonyOS\Projects\DeviceDemo
D:\HarmonyOS\Sdk

4.3 Linux 环境准备

检查：
• 发行版版本；
• 图形桌面环境；
• JDK、Node.js 等依赖；
• USB 权限和设备规则；
• 用户组配置；
• 图形驱动；
• 模拟器虚拟化支持。
Linux 下设备可以被系统识别，但当前用户没有访问权限，因此需要检查设备权限和规则配置。

4.4 macOS 环境准备

检查：
• 系统版本；
• 芯片架构；
• DevEco Studio 对当前架构的支持；
• USB 设备权限；
• 网络和证书；
• JDK 和 SDK 版本；
• 模拟器图形性能。

4.5 操作系统选择原则

不要在同一项目开发过程中频繁切换系统和工具版本，否则排错难度会增加。

5.DevEco Studio 与 JDK 安装

5.1 DevEco Studio 安装

通用步骤：

1. 从官方渠道获取适合当前系统的安装包。
2. 阅读许可协议和安装说明。
3. 选择安装目录。
4. 安装 IDE 及必要组件。
5. 首次启动并完成基础设置。
6. 配置 SDK 保存位置。
7. 创建或打开一个最小工程。
8. 完成一次同步、编译和运行。
   安装路径建议

Windows: D:\HarmonyOS\DevEcoStudio
Linux:   /opt/harmonyos/deveco
macOS:   /Applications/DevEco Studio.app

具体路径可按学校或团队规范设置。路径不宜过长，也不宜包含大量特殊字符。

5.2 JDK 的作用

JDK 为 Java 相关构建工具提供运行环境。部分鸿蒙项目的构建过程依赖 JDK，因此 JDK 版本必须与 DevEco Studio、构建工具和项目要求兼容。
JDK 版本不匹配可能导致：
• IDE 无法启动；
• Gradle 构建失败；
• 编译器报类版本错误；
• 依赖解析异常；
• 工程同步失败；
• 运行时出现不可理解的错误。

5.3 JDK 检查

终端执行：

java --version
javac --version

如果命令无法识别：
• 检查 JDK 是否安装；
• 检查 PATH；
• 检查 JAVA_HOME 或 IDE 内部 JDK 配置；
• 重新打开终端和 IDE；
• 检查系统中是否存在多个 JDK。

5.4 JDK 配置原则

• 优先使用当前 DevEco Studio 推荐的 JDK。
• 项目团队统一 JDK 主版本。
• 不要只修改系统 PATH 而忽略 IDE 的 JDK 设置。
• 记录实际使用的 JDK 版本。
• 升级 JDK 前先确认项目构建兼容性。
• 不要把 JDK 安装目录误删当作清理缓存。

5.5 环境变量

常见环境变量作用：

修改环境变量前：

1. 记录原有值；
2. 只增加必要路径；
3. 避免重复添加；
4. 重新打开终端；
5. 用版本命令验证。

6.SDK Manager 配置

6.1 SDK Manager 的作用

SDK Manager 用于：
• 查看已安装 SDK；
• 安装指定 API 或平台；
• 管理构建工具；
• 管理设备工具；
• 下载模拟器镜像；
• 更新或删除不需要的组件。

6.2 SDK 组件类型

常见组件类别：

平台 SDK
构建工具
命令行工具
设备调试工具
模拟器系统镜像
预览器相关组件
模板和示例

不同课程和项目所需组件可能不同。不要无目的安装全部组件，以免占用大量磁盘空间和增加版本冲突。

6.3 SDK 版本选择

原则：
• 使用课程或项目规定的版本；
• 没有规定时选择当前稳定版本；
• 保留能复现项目的版本；
• 升级前提交代码并记录变更；
• 不同模块尽量使用兼容的 API 版本；
• 发现 API 差异时查看迁移说明。

6.4 SDK 路径

SDK 路径应满足：
• 目录真实存在；
• 当前用户有读写权限；
• 路径没有明显特殊字符；
• 磁盘空间充足；
• IDE 能够识别平台和工具；
• 团队成员可以根据文档复现。
常见问题：

SDK 目录存在，但缺少构建工具
SDK 安装到了权限受限目录
项目引用旧 SDK
多个 SDK 版本造成选择混乱
下载过程中断导致组件不完整

6.5 SDK 安装验收

• [ ] 目标 API 或平台已经安装。
• [ ] 构建工具可用。
• [ ] 设备调试工具可用。
• [ ] 需要的模拟器镜像已安装。
• [ ] SDK Manager 没有未完成或损坏的组件。
• [ ] 工程可以识别正确 SDK。
• [ ] 最小项目可以成功编译。

7.设备连接与调试

7.1 实体设备调试流程

设备准备
  ↓
开启开发者/调试能力
  ↓
安装 USB 驱动或配置设备权限
  ↓
数据线连接
  ↓
设备授权
  ↓
IDE 识别设备
  ↓
安装并运行应用
  ↓
查看日志和调试结果

具体开发者选项、授权方式和设备连接界面可能随设备型号和系统版本变化。

7.2 USB 驱动

Windows 通常需要安装对应 USB 驱动。Linux 和 macOS 可能更多涉及：
• 设备访问权限；
• 用户组；
• 设备规则；
• 系统隐私授权；
• 数据线和接口兼容性。
驱动安装后应重新连接设备，并检查 IDE 是否能够识别。

7.3 设备识别排查

1.设备完全不显示

检查：

1. 数据线是否支持数据传输；
2. USB 端口是否正常；
3. 设备是否已解锁；
4. 是否确认了调试授权；
5. 驱动是否安装；
6. 系统是否识别设备；
7. IDE 是否选择了正确 SDK 和工具；
8. 是否存在其他程序占用设备。

2.设备反复连接断开

可能原因：
• 数据线质量不稳定；
• USB 集线器供电不足；
• 驱动不兼容；
• 设备电量低；
• 系统 USB 节能；
• 设备端调试服务重启。
改进：
• 更换数据线和端口；
• 直接连接主机端口；
• 重新安装或更新驱动；
• 重启设备和 IDE；
• 观察设备日志。

7.4 调试授权与安全

连接真机时，设备可能要求确认调试授权。注意：
• 只授权可信计算机；
• 不在公共电脑上永久授权；
• 测试完成后关闭不需要的调试能力；
• 不把设备中的个人数据带入测试包；
• 不将授权截图和设备信息公开发布。

7.5 真机运行验证

安装后至少验证：
• 应用能够启动；
• 页面内容完整；
• 点击和输入有效；
• 权限申请符合预期；
• 日志无严重错误；
• 返回和退出正常；
• 设备旋转或屏幕变化时界面可用；
• 网络异常时有提示；
• 卸载和重新安装行为正常。

8.鸿蒙模拟器使用

8.1 模拟器的作用

模拟器可以在没有实体设备时帮助完成：
• 页面布局开发；
• 基础交互测试；
• 路由和状态验证；
• 网络异常模拟；
• 日志和断点调试；
• 多尺寸设备预览。

8.2 创建虚拟设备

通用步骤：

1. 打开 DevEco Studio 的设备管理工具。
2. 选择目标设备类型。
3. 选择对应系统镜像。
4. 配置虚拟设备名称和存储。
5. 创建并启动模拟器。
6. 等待系统完成启动。
7. 在 IDE 中选择该模拟器运行工程。

8.3 模拟器性能

模拟器会占用：
• 内存；
• CPU；
• 磁盘；
• 图形资源；
• 虚拟化能力。
启动慢或卡顿时：
• 关闭不必要的程序；
• 检查虚拟化设置；
• 降低模拟器分辨率或资源；
• 避免同时启动多个模拟器；
• 使用预览器完成纯布局工作；
• 清理明确的无用快照。

8.4 模拟器与真机的差异

结论：模拟器适合快速开发，真机适合最终验证。两者应结合使用。

9.编译与构建

9.1 编译和构建的区别

可以简单理解为：
• 编译：检查代码并把源代码转换为中间产物或目标代码。
• 构建：综合执行依赖解析、编译、资源处理、打包和签名等步骤。
• 部署：将构建产物安装到模拟器或实体设备。

源代码
  ↓
编译
  ↓
资源处理和依赖
  ↓
构建
  ↓
安装包
  ↓
部署和运行

9.2 Gradle 与 CMake

课程材料提到 Gradle 或 CMake。实际使用哪一种，取决于项目中是否包含：
• Java/Kotlin 或相关构建配置；
• Native/C/C++ 代码；
• 第三方原生库；
• 特定模块和工具链。
不要因为看到项目中有某个脚本，就直接修改全部构建配置。先判断：
这是应用主构建流程？
还是某个原生模块的局部构建？

9.3 构建过程中的阶段

读取工程配置
  ↓
解析依赖
  ↓
检查 SDK
  ↓
编译 ArkTS/其他源码
  ↓
处理资源
  ↓
编译原生模块（如有）
  ↓
生成安装包
  ↓
签名或测试打包

9.4 常见构建问题

1.找不到 SDK

原因：
• SDK 路径错误；
• 目标 API 未安装；
• 工程引用了不存在的版本；
• 权限不足。

2.JDK 不兼容

原因：
• JDK 版本过旧或过新；
• IDE 和命令行使用不同 JDK；
• 构建工具要求不同版本。

3.依赖解析失败

原因：
• 网络问题；
• 仓库不可用；
• 依赖版本不存在；
• 缓存损坏；
• 配置文件错误。

4.资源找不到

原因：
• 资源文件路径错误；
• 文件名大小写不一致；
• 配置引用名称错误；
• 资源没有加入正确目录。

5.构建时间过长

原因：
• 首次索引和依赖下载；
• 工程规模大；
• 磁盘速度慢；
• 内存不足；
• 模拟器和构建同时占用资源。

9.5 构建排错方法

读取第一条真正错误
  ↓
定位文件和行号
  ↓
判断配置、依赖、代码还是环境问题
  ↓
用最小修改验证
  ↓
重新构建
  ↓
记录修复结果

不要只复制最后一行错误去搜索。后续错误往往是前面一个根因错误的连锁结果。

10.测试与部署

10.1 测试层次

代码级测试
  ↓
页面和组件测试
  ↓
工程构建测试
  ↓
模拟器运行测试
  ↓
真机运行测试
  ↓
安装、升级和卸载测试

10.2 基础功能测试

至少测试：
• 应用启动；
• 页面显示；
• 按钮点击；
• 输入框输入；
• 页面跳转；
• 数据读取；
• 错误提示；
• 返回和退出；
• 权限申请；
• 横竖屏或尺寸变化。

10.3 异常测试

测试：
• 断网；
• 请求超时；
• 数据为空；
• 数据格式错误；
• 权限拒绝；
• 设备断开；
• SDK 版本不一致；
• 磁盘空间不足；
• 重复点击；
• 后台恢复。

10.4 部署验证

构建成功
  ↓
安装到模拟器/真机
  ↓
启动应用
  ↓
运行主流程
  ↓
查看日志
  ↓
记录设备、系统和构建版本

安装失败时检查：
• 包是否与设备兼容；
• 签名是否有效；
• 设备空间是否充足；
• 旧版本是否冲突；
• 调试授权是否有效；
• 构建产物是否完整。

10.5 升级和卸载测试

升级
检查：
• 用户数据是否保留；
• 数据库是否需要迁移；
• 配置是否兼容；
• 新旧版本权限是否变化；
• 卡片和桌面入口是否正常。
卸载
检查：
• 是否按预期清理数据；
• 是否有需要保留的用户数据；
• 重新安装后是否能重新初始化；
• 调试授权是否仍有效。

11.完整实践：搭建并验证一个鸿蒙硬件开发环境

11.1 实践目标

完成一个最小闭环：

检查计算机
  ↓
安装系统依赖
  ↓
安装 DevEco Studio
  ↓
配置 JDK 和 SDK
  ↓
创建工程
  ↓
连接模拟器或真机
  ↓
编译并安装
  ↓
运行和查看日志
  ↓
记录环境和问题

11.2 实践步骤

1. 第一步：记录环境
   操作系统：
   处理器：
   内存：
   磁盘：
   JDK：
   DevEco Studio：
   SDK：
   测试设备：
2. 第二步：安装和配置
   • 安装 DevEco Studio；
   • 配置 JDK；
   • 使用 SDK Manager 安装课程要求的组件；
   • 检查项目路径；
   • 创建最小工程。
3. 第三步：运行默认页面
   • 编译项目；
   • 选择模拟器或真机；
   • 安装并运行；
   • 查看页面和日志；
   • 截图记录结果。
4. 第四步：修改页面
   例如修改页面标题：

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('鸿蒙硬件开发环境验证成功')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

5. 第五步：验证设备连接
   • 重新运行；
   • 检查设备列表；
   • 断开并重新连接；
   • 观察设备是否稳定识别；
   • 查看调试日志。
6. 第六步：提交环境报告
   报告包含：
   • 硬件和系统信息；
   • 安装步骤；
   • 版本和路径；
   • 运行截图；
   • 遇到的问题；
   • 解决方案；
   • 当前环境限制；
   • 后续改进建议。

12. 常见问题与排查清单

13.工程伦理与安全要求

1. 安装来源可靠
   • 从官方渠道获取 IDE、SDK 和驱动；
   • 不使用来源不明的破解包；
   • 不安装无法确认用途的脚本或插件；
   • 检查下载文件和安装包来源。
2. 保护开发机
   • 使用普通用户进行日常开发；
   • 安装驱动时确认权限和来源；
   • 重要项目定期备份；
   • 不随意修改系统目录；
   • 不执行来源不明的清理脚本；
   • 不把整个用户目录作为清理目标。
3. 保护设备和数据
   • 只连接可信测试设备；
   • 不在公共设备上保留调试授权；
   • 不将个人照片、联系人和账号带入测试包；
   • 日志和截图需要脱敏；
   • 不在代码中提交密钥和密码。
4. 自主创新与职业道德
   自主创新需要建立在：
   • 理解工具原理；
   • 独立分析问题；
   • 规范引用资料；
   • 尊重知识产权；
   • 诚实记录实验结果；
   • 对代码和设备行为负责。
   不能把“环境能运行”作为唯一目标。一个可交付环境还需要可复现、可解释、可维护和安全。

14.课堂实践任务

1.任务一：环境检查

完成硬件和系统检查表：

处理器
内存
磁盘
操作系统
JDK
DevEco Studio
SDK
模拟器/真机

说明你的计算机适合：
• 只做代码编辑；
• 运行预览器；
• 运行模拟器；
• 进行真机调试；
中的哪一种或哪几种场景。

2.任务二：安装 DevEco Studio

要求：
• 记录安装目录；
• 记录 JDK 配置；
• 记录 SDK 路径；
• 安装课程要求的 SDK；
• 创建最小工程；
• 完成首次编译。

3.任务三：设备连接

要求：
• 连接一台可信测试设备或模拟器；
• 观察 IDE 识别结果；
• 运行默认工程；
• 查看日志；
• 断开并重新连接；
• 记录设备连接问题。

4.任务四：构建和部署

要求：
• 修改页面文字；
• 编译构建；
• 安装到目标设备；
• 验证应用启动；
• 验证返回和退出；
• 保存构建结果和截图。

5.任务五：环境故障模拟

任选两项进行分析：
• 删除或切换错误 SDK；
• 使用不兼容 JDK；
• 断开网络后同步工程；
• 拔出设备数据线；
• 模拟器内存不足；
• 使用错误工程路径。
要求记录：
现象
原因假设
排查过程
修复方法
验证结果

6.任务六：环境安装报告

提交一份 800～1500 字报告，建议包含：

1. 硬件和操作系统；
2. 工具版本和路径；
3. 安装步骤；
4. 工程创建和运行结果；
5. 设备或模拟器连接结果；
6. 遇到的问题；
7. 解决方法；
8. 当前环境限制；
9. 后续改进计划。

15.章节验收清单

1.硬件和系统

• [ ] 能说明处理器、内存和磁盘对开发环境的影响。
• [ ] 能根据当前工具链要求检查计算机。
• [ ] 能说明 Windows、Linux、macOS 等系统的准备事项。
• [ ] 项目路径和 SDK 路径清晰、可复现。
• [ ] 网络和权限条件满足安装需要。

2.工具安装

• [ ] DevEco Studio 安装成功。
• [ ] JDK 版本与工具链兼容。
• [ ] 能使用 java --version 检查 JDK。
• [ ] SDK Manager 能正常打开。
• [ ] 课程要求的 SDK 和工具链已安装。
• [ ] 能创建并打开最小工程。

3.设备和模拟器

• [ ] 能安装或配置 USB 驱动。
• [ ] 真机能够被 IDE 识别，或模拟器能够启动。
• [ ] 理解调试授权和设备安全。
• [ ] 能安装并运行测试应用。
• [ ] 能查看运行日志。
• [ ] 了解模拟器和真机的差异。

4.编译和部署

• [ ] 能完成工程同步和编译。
• [ ] 能理解编译、构建和部署的关系。
• [ ] 能判断 Gradle/CMake 等构建脚本的作用范围。
• [ ] 能处理基本依赖、SDK 和资源错误。
• [ ] 能完成测试包安装。
• [ ] 能执行基础功能和异常测试。

5.工程实践

• [ ] 提交了环境安装记录。
• [ ] 记录了至少一个问题及解决方法。
• [ ] 能根据日志进行分层排查。
• [ ] 对开发环境限制有明确说明。
• [ ] 遵守软件来源、设备安全和数据保护要求。
• [ ] 能说明如何让团队成员复现环境。