DevEco Studio 在 Windows 系统上的完整安装、配置与卸载全面使用指南

DevEco Studio 在 Windows 系统上的完整安装、配置与卸载全面使用指南

摘要

HUAWEI DevEco Studio 是华为面向 HarmonyOS（鸿蒙操作系统）应用及元服务开发的官方一站式集成开发环境（IDE），基于 IntelliJ IDEA Community 开源版本打造。它为开发者提供了从工程模板创建、代码编写、UI 设计、编译构建、模拟调试到签名发布的端到端（E2E）开发体验。随着 HarmonyOS NEXT（纯血鸿蒙）的正式发布，DevEco Studio 5.0 系列已成为鸿蒙原生应用开发的唯一官方工具。

本指南以 Windows 系统 为核心平台，涵盖从环境准备、软件安装、SDK 配置、项目创建、调试运行到完全卸载的全生命周期操作。文章包含详尽的步骤说明、实际代码示例、配置参数解读、常见问题排查及最佳实践建议，适合零基础新手和有经验的开发者参考使用。

适用版本：DevEco Studio 5.0.x Release（API 12+ / HarmonyOS NEXT） 适用系统：Windows 10 64位 / Windows 11 64位 最后更新：2026年7月

目录

• 一、DevEco Studio 概述与核心特性
  • 1.1 什么是 DevEco Studio
  • 1.2 DevEco Studio 的发展演进
  • 1.3 核心功能模块一览
  • 1.4 DevEco Studio 与其他 IDE 的对比
• 二、环境准备与前置条件
  • 2.1 操作系统要求
  • 2.2 硬件配置要求
  • 2.3 网络环境要求
  • 2.4 华为开发者账号准备
  • 2.5 系统环境变量预检
• 三、下载与安装 DevEco Studio
  • 3.1 从官网下载安装包
  • 3.2 安装包完整性校验
  • 3.3 安装步骤详解
  • 3.4 安装选项说明
  • 3.5 安装完成验证
• 四、首次启动与初始化配置
  • 4.1 首次启动向导
  • 4.2 用户协议与隐私声明
  • 4.3 SDK 自动下载与安装
  • 4.4 Node.js 与 OHPM 环境配置
  • 4.5 初始化完成验证
• 五、SDK 管理与环境深度配置
  • 5.1 HarmonyOS SDK 组成结构
  • 5.2 SDK Manager 使用详解
  • 5.3 配置 SDK 路径与版本
  • 5.4 Node.js 与 OHPM 配置
  • 5.5 环境变量配置详解
  • 5.6 代理与镜像配置
• 六、项目创建与工程结构详解
  • 6.1 创建新项目
  • 6.2 工程模板类型说明
  • 6.3 项目目录结构详解
  • 6.4 关键配置文件解读
  • 6.5 多模块工程管理
• 七、ArkTS 开发实战与代码示例
  • 7.1 ArkTS 语言基础
  • 7.2 声明式 UI 开发
  • 7.3 状态管理详解
  • 7.4 页面路由与导航
  • 7.5 网络请求与数据展示
  • 7.6 完整项目实战示例
• 八、调试与运行
  • 8.1 模拟器（Emulator）配置与使用
  • 8.2 真机调试配置
  • 8.3 预览器（Previewer）使用
  • 8.4 断点调试与日志输出
  • 8.5 性能分析工具
• 九、签名、打包与发布
  • 9.1 调试证书与发布证书
  • 9.2 自动签名配置
  • 9.3 手动签名配置
  • 9.4 构建 HAP/APP 包
  • 9.5 发布到 AppGallery Connect
• 十、高级配置与优化
  • 10.1 IDE 个性化设置
  • 10.2 插件管理与扩展
  • 10.3 编译构建优化
  • 10.4 版本控制集成（Git）
  • 10.5 CodeGenie AI 辅助开发
• 十一、常见问题排查与解决方案
  • 11.1 安装类问题
  • 11.2 SDK 与依赖类问题
  • 11.3 编译构建类问题
  • 11.4 模拟器与调试类问题
  • 11.5 性能与稳定性问题
• 十二、完整卸载与残留清理
  • 12.1 常规卸载流程
  • 12.2 清理残留文件与目录
  • 12.3 清理注册表残留
  • 12.4 清理环境变量
  • 12.5 使用第三方工具彻底卸载
  • 12.6 卸载验证清单
• 十三、总结与最佳实践
• 附录
  • 附录A：DevEco Studio 快捷键速查表
  • 附录B：环境变量与配置文件速查表
  • 附录C：HDC 命令行工具常用命令
  • 附录D：项目配置文件参数详解
  • 附录E：推荐学习资源

一、DevEco Studio 概述与核心特性

1.1 什么是 DevEco Studio

HUAWEI DevEco Studio（以下简称 DevEco Studio）是华为为 HarmonyOS 操作系统量身定制的一站式集成开发环境（IDE）。它基于 JetBrains IntelliJ IDEA Community 开源版本深度定制，面向华为终端全场景多设备的应用和元服务开发，提供了从项目创建、代码编写、UI 设计、编译构建、调试测试到签名发布的全流程开发能力。

DevEco Studio 的设计目标是 “开箱即用”，它将 HarmonyOS SDK、Node.js 运行时、Hvigor 构建工具、OHPM（OpenHarmony Package Manager）包管理器、模拟器平台等进行了一体化打包，极大地简化了开发环境的安装配置流程。

核心定位：

• 面向 HarmonyOS NEXT（纯血鸿蒙）的原生应用开发
• 支持 ArkTS/ArkUI 声明式 UI 开发范式
• 覆盖手机、平板、PC、智慧屏、穿戴设备等多设备形态
• 支持应用（App）和元服务（Atomic Service）两种产品形态

1.2 DevEco Studio 的发展演进

1.3 核心功能模块一览

DevEco Studio 核心功能模块
├── 代码编辑器
│ ├── ArkTS/TypeScript 智能补全
│ ├── 代码重构（Extract Method, Inline, Rename…）
│ ├── 实时语法检查与错误提示
│ └── 代码模板与片段（Snippets）
├── UI 设计
│ ├── ArkUI 声明式 UI 编辑
│ ├── 实时预览（Previewer）
│ ├── 多设备适配预览
│ └── 组件属性面板
├── 调试与测试
│ ├── 本地模拟器（Emulator）
│ ├── 真机调试（HDC 工具链）
│ ├── 断点调试 / 条件断点
│ ├── 日志查看（HiLog）
│ └── 单元测试框架
├── 编译构建
│ ├── Hvigor 构建系统
│ ├── 增量编译
│ ├── 构建产物分析
│ └── 签名与打包
├── 性能分析
│ ├── 内存分析
│ ├── CPU 分析
│ ├── 帧率分析
│ └── ArkTS 内存泄漏检测
├── AI 辅助
│ ├── CodeGenie 智能编码助手
│ ├── 代码生成与解释
│ └── 智能重构建议
└── 项目管理
├── 多模块工程支持
├── OHPM 依赖管理
├── Git 版本控制集成
└── 项目模板市场

1.4 DevEco Studio 与其他 IDE 的对比

二、环境准备与前置条件

2.1 操作系统要求

DevEco Studio 在 Windows 系统上的操作系统要求如下：

重要提示：请确保系统已安装最新的 Windows 更新补丁。可通过 设置 → Windows 更新 检查并安装更新。

2.2 硬件配置要求

为确保 DevEco Studio 流畅运行，建议满足以下硬件配置：

特别说明：

• 内存：DevEco Studio 本身运行约需 2-4 GB 内存，模拟器约需 4 GB，加上系统和其他应用程序，16 GB 是流畅开发的最低保障。
• 硬盘：强烈建议使用 SSD，编译构建速度可提升 3-5 倍。SDK、模拟器镜像、项目文件总计可能占用 30-60 GB。
• CPU 虚拟化：如需使用模拟器，需在 BIOS 中开启 Intel VT-x 或 AMD-V 虚拟化技术。

2.3 网络环境要求

DevEco Studio 在首次启动时需要下载 SDK、工具链和模拟器镜像，对网络有以下要求：

网络优化建议：如果下载速度较慢，可以配置代理服务器或使用华为云镜像加速。具体配置方法详见 5.6 代理与镜像配置。

2.4 华为开发者账号准备

在使用 DevEco Studio 之前，您需要一个华为开发者账号：

注册步骤：

步骤 1：访问华为开发者联盟官网
https://developer.huawei.com/consumer/cn/

步骤 2：点击右上角"注册"按钮

步骤 3：选择注册方式
– 手机号注册（推荐）
– 邮箱注册

步骤 4：完成实名认证
– 个人开发者：身份证认证
– 企业开发者：营业执照认证

步骤 5：同意开发者协议，完成注册

提示：实名认证是进行应用签名和发布的必要条件。个人开发者可以免费进行开发和调试，但发布应用需要加入华为开发者计划。

2.5 系统环境变量预检

在安装 DevEco Studio 之前，建议检查并清理可能冲突的环境变量：

PowerShell 检查命令：

# 检查是否已存在 Node.js 环境
node —version
# 输出示例：v18.18.2 或 "node 不是内部或外部命令"

# 检查是否已存在 OHPM 环境
ohpm —version
# 输出示例：1.2.3 或 "ohpm 不是内部或外部命令"

# 检查 JAVA_HOME 环境变量
echo $env:JAVA_HOME
# DevEco Studio 自带 JDK，一般无需额外配置

# 检查 PATH 中是否有冲突路径
$env:PATH –split ';' | Select-String –Pattern "deveco|harmonyos|ohos"

如果存在旧版本 Node.js 或 OHPM：

• DevEco Studio 5.0+ 已内置 Node.js 和 OHPM，通常无需额外安装
• 如果系统中有旧版本，建议先卸载或在安装时选择使用 DevEco Studio 内置版本
• 避免 PATH 中存在多个 Node.js 路径导致版本冲突

三、下载与安装 DevEco Studio

3.1 从官网下载安装包

下载步骤：

步骤 1：打开浏览器，访问华为开发者联盟下载中心
最新版本：https://developer.huawei.com/consumer/cn/download/
历史版本：https://developer.huawei.com/consumer/cn/deveco-studio/

步骤 2：登录华为开发者账号（如未登录会提示登录）

步骤 3：在下载页面选择
– 产品：DevEco Studio
– 版本：选择最新 Release 版本（如 5.0.5.306）
– 平台：Windows（x64）

步骤 4：点击"下载"按钮，等待下载完成
下载文件示例：devecostudio-windows-5.0.5.306.zip
文件大小：约 1.5 – 2.5 GB

版本选择建议：

3.2 安装包完整性校验

下载完成后，建议对安装包进行完整性校验，确保文件未被篡改或损坏：

使用 PowerShell 校验 SHA-256：

# 步骤 1：打开 PowerShell（以管理员身份运行）

# 步骤 2：计算下载文件的 SHA-256 哈希值
$filePath = "C:\\Users\\YourName\\Downloads\\devecostudio-windows-5.0.5.306.zip"
$hash = Get-FileHash –Path $filePath –Algorithm SHA256
Write-Output "文件 SHA-256: $($hash.Hash)"

# 步骤 3：将计算出的哈希值与官网提供的哈希值进行对比
# 如果一致，说明文件完整无损
# 如果不一致，请重新下载

使用 certutil 命令校验：

# 使用 Windows 内置的 certutil 工具
certutil –hashfile "C:\\Users\\YourName\\Downloads\\devecostudio-windows-5.0.5.306.zip" SHA256

# 输出示例：
# SHA256 哈希:
# a1b2c3d4e5f6…
# CertUtil: -hashfile 命令成功完成。

3.3 安装步骤详解

第一步：解压安装包

1. 找到下载的 zip 文件（如 devecostudio-windows-5.0.5.306.zip）
2. 右键 → "全部解压缩" 或使用 7-Zip/WinRAR 解压
3. 解压后得到安装程序文件：
deveco-studio-5.0.5.306.exe

第二步：启动安装程序

1. 双击 deveco-studio-5.0.5.306.exe 启动安装向导
2. 如果弹出 UAC（用户账户控制）提示，点击"是"允许运行
3. 等待安装向导初始化完成

第三步：选择安装路径

1. 在安装向导界面中，默认安装路径通常为：
C:\\Users\\<用户名>\\AppData\\Local\\Huawei\\DevEcoStudio

2. 建议修改到非系统盘以节省 C 盘空间，例如：
D:\\Huawei\\DevEcoStudio

3. 点击"Browse"按钮选择自定义安装路径

4. 点击"Next"继续

路径建议：安装路径中不要包含中文、空格或特殊字符，以免编译构建时出现路径解析错误。

第四步：选择安装选项

安装选项界面提供以下勾选项（建议全部勾选）：

☑ Create Desktop Shortcut – 创建桌面快捷方式
☑ Create Start Menu Shortcut – 创建开始菜单快捷方式
☑ Update PATH Variable – 更新系统 PATH 环境变量（推荐）
☑ Add 'HDC_SERVER_PORT' – 添加 HDC 服务端端口环境变量
☑ Associate .ets Files – 关联 .ets 文件类型

点击"Next"继续

第五步：确认安装

1. 确认安装路径和选项无误
2. 点击"Install"开始安装
3. 等待安装进度条完成（约 3-8 分钟，取决于硬盘速度）
4. 安装完成后点击"Finish"
5. 可选择"Restart Now"立即重启或"Restart Later"稍后重启

3.4 安装选项说明

3.5 安装完成验证

安装完成后，进行以下验证：

# 验证 1：检查安装目录是否完整
# 打开安装目录，应包含以下关键文件夹和文件：
# D:\\Huawei\\DevEcoStudio\\
# ├── bin\\ # IDE 可执行文件
# │ └── deveco-studio64.exe
# ├── tools\\ # 开发工具链
# │ ├── hdc\\ # HDC 调试工具
# │ ├── node\\ # 内置 Node.js
# │ ├── ohpm\\ # 内置 OHPM
# │ └── hvigor\\ # 构建工具
# ├── plugins\\ # IDE 插件
# ├── jbr\\ # 内置 JBR (JetBrains Runtime)
# └── …

# 验证 2：通过命令行验证工具可用性
# 打开新的 PowerShell 窗口（安装后需重新加载 PATH）

# 检查 hdc 工具
hdc version
# 预期输出：Ver: x.x.x

# 检查 Node.js（如果使用内置版本）
# 注意：内置 Node.js 可能需要通过 DevEco Studio 终端使用
node —version
# 预期输出：v18.x.x 或 v20.x.x

# 检查 OHPM
ohpm —version
# 预期输出：x.x.x

四、首次启动与初始化配置

4.1 首次启动向导

安装完成后，双击桌面快捷方式或在开始菜单中搜索"DevEco Studio"启动：

首次启动流程：

1. 启动画面 → 显示 DevEco Studio Logo 和版本号
2. 加载插件和组件（首次较慢，约 30-60 秒）
3. 进入"Welcome to DevEco Studio"欢迎界面
4. 弹出用户协议和隐私声明对话框

4.2 用户协议与隐私声明

首次启动时会弹出用户协议和隐私声明：

1. 仔细阅读《华为开发者联盟用户协议》
2. 仔细阅读《隐私声明》
3. 勾选"我已阅读并同意以上协议"
4. 点击"OK"或"Accept"继续

注意：必须同意协议才能继续使用 DevEco Studio。

4.3 SDK 自动下载与安装

DevEco Studio 首次启动后会自动检测并下载所需的 SDK 和工具组件：

自动下载流程：

1. IDE 启动后会自动打开"SDK Download"对话框
2. 显示需要下载的组件列表：
├── HarmonyOS SDK (API 12/13/14…)
│ ├── Toolchains # 编译工具链
│ ├── ETS SDK # ArkTS SDK
│ ├── JS SDK # JavaScript SDK
│ └── Native SDK # C/C++ Native SDK（可选）
├── DevEco Studio Tools
│ ├── HDC # 设备连接调试工具
│ ├── Previewer # UI 预览器
│ └── Emulator # 模拟器平台
└── 运行时环境
├── Node.js # JavaScript 运行时
└── OHPM # 包管理器

3. 选择要安装的组件（建议保持默认全选）
4. 选择 SDK 安装路径（建议与 IDE 安装路径相同磁盘）
默认路径：C:\\Users\\<用户名>\\AppData\\Local\\Huawei\\Sdk
建议路径：D:\\Huawei\\Sdk
5. 点击"Next"开始下载
6. 等待下载和安装完成（约 15-40 分钟，取决于网络速度）
7. 点击"Finish"完成

SDK 下载大小参考：

4.4 Node.js 与 OHPM 环境配置

DevEco Studio 5.0+ 版本已内置 Node.js 和 OHPM，首次启动时会自动配置：

自动配置流程：

1. DevEco Studio 检测系统中是否已有 Node.js
– 如果有：提示选择使用系统版本或内置版本
– 如果没有：自动使用内置版本

2. Node.js 配置
– 内置 Node.js 路径：{DevEco Studio安装目录}\\tools\\node\\
– 版本通常为 v18.x 或 v20.x LTS

3. OHPM 配置
– 内置 OHPM 路径：{DevEco Studio安装目录}\\tools\\ohpm\\
– 自动配置 OHPM 仓库地址
– 默认仓库：https://ohpm.openharmony.cn/ohpm/

4. Hvigor 构建工具
– 随项目模板自动配置
– 基于 Node.js 运行的构建框架

最佳实践：建议统一使用 DevEco Studio 内置的 Node.js 和 OHPM 版本，避免版本不兼容导致的构建问题。

4.5 初始化完成验证

完成所有初始化配置后，进行以下验证：

验证步骤：

1. 打开 DevEco Studio 主界面
– 确认顶部标题栏显示正确的版本号
– 确认底部状态栏没有错误提示

2. 检查 SDK 状态
– 菜单：File → Project Structure → SDK
– 确认 HarmonyOS SDK 路径正确
– 确认 SDK 版本已选择（如 API 12）

3. 检查工具链
– 菜单：File → Settings → HarmonyOS SDK
– 确认各组件状态为"Installed"

4. 创建测试项目
– File → New → Create Project
– 选择"Empty Ability"模板
– 确认项目创建成功并能正常编译

5. 验证预览器
– 打开一个 .ets 文件
– 点击右侧"Preview"面板
– 确认 UI 预览正常渲染

五、SDK 管理与环境深度配置

5.1 HarmonyOS SDK 组成结构

HarmonyOS SDK 是开发 HarmonyOS 应用的核心依赖，其目录结构如下：

HarmonyOS SDK 目录结构
{SDK_ROOT}/
├── HarmonyOS-NEXT/ # HarmonyOS NEXT SDK
│ ├── openharmony/ # OpenHarmony 基础 SDK
│ │ └── {API_VERSION}/ # 如 12、13、14
│ │ ├── ets/ # ArkTS API 定义
│ │ │ ├── api/ # 系统 API 声明文件
│ │ │ ├── component/ # UI 组件定义
│ │ │ └── build-tools/# 构建工具
│ │ ├── toolchains/ # 编译工具链
│ │ │ ├── hvigor/ # Hvigor 构建工具
│ │ │ ├── hdc/ # HDC 调试工具
│ │ │ └── llvm/ # LLVM 编译器（Native 开发）
│ │ ├── previewer/ # 预览器运行时
│ │ └── emulator/ # 模拟器镜像与运行时
│ └── harmonyos/ # HarmonyOS 扩展 SDK（华为专有）
│ └── {API_VERSION}/
│ └── ets/ # 华为专有 API
├── toolchains/ # 全局工具链
│ ├── node/ # Node.js 运行时
│ ├── ohpm/ # OHPM 包管理器
│ └── hvigor/ # Hvigor 构建框架
└── .config/ # SDK 配置文件

5.2 SDK Manager 使用详解

SDK Manager 是管理 SDK 组件的核心工具：

打开方式：

方法 1：菜单 → Tools → SDK Manager
方法 2：File → Project Structure → SDK
方法 3：欢迎界面 → Configure → SDK Manager
方法 4：快捷键 → Ctrl + Alt + S（打开设置后搜索 "SDK"）

SDK Manager 界面说明：

SDK Manager 界面分为以下标签页：

┌─────────────────────────────────────────────────┐
│ SDK Manager │
├─────────┬───────────────────────────────────────┤
│ │ │
│ SDK │ ☑ HarmonyOS SDK (API 12) │
│ Platforms│ ☑ HarmonyOS SDK (API 13) │
│ │ ☐ HarmonyOS SDK (API 14) [Preview] │
│ ───── │ │
│ SDK │ ☑ Toolchains │
│ Tools │ ☑ HDC │
│ │ ☑ Previewer │
│ │ ☐ Emulator – Phone │
│ │ ☐ Emulator – Tablet │
│ │ ☐ Native (C/C++) Support │
│ │ │
├─────────┴───────────────────────────────────────┤
│ SDK Location: D:\\Huawei\\Sdk │
│ [Apply] [OK] [Cancel] │
└─────────────────────────────────────────────────┘

常用操作：

5.3 配置 SDK 路径与版本

修改 SDK 路径：

场景：将 SDK 从 C 盘迁移到 D 盘

步骤 1：关闭 DevEco Studio

步骤 2：将 SDK 目录从原路径复制到新路径
原路径：C:\\Users\\YourName\\AppData\\Local\\Huawei\\Sdk
新路径：D:\\Huawei\\Sdk

PowerShell 命令：
Copy-Item -Path "C:\\Users\\YourName\\AppData\\Local\\Huawei\\Sdk" `
-Destination "D:\\Huawei\\Sdk" -Recurse

步骤 3：重新打开 DevEco Studio

步骤 4：进入 File → Project Structure → SDK

步骤 5：将 SDK Location 修改为 D:\\Huawei\\Sdk

步骤 6：点击 Apply → OK

步骤 7：删除原路径下的 SDK 文件夹以释放 C 盘空间

配置项目使用的 SDK 版本：

在项目根目录的 build-profile.json5 文件中配置：

// build-profile.json5 – 项目级构建配置
{
"app": {
// 签名配置
"signingConfigs": [],
"products": [
{
"name": "default",
"signingConfig": "default",
// 指定编译的 API 版本
"compileSdkVersion": "5.0.0(12)",
// 指定最低兼容 API 版本
"compatibleSdkVersion": "5.0.0(12)",
// 构建产物类型
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true
}
}
}
],
// 构建模式集合
"buildModeSet": [
{
"name": "debug"
},
{
"name": "release"
}
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
}
]
}
]
}

5.4 Node.js 与 OHPM 配置

Node.js 配置：

DevEco Studio 内置 Node.js 路径：
{DevEco安装目录}\\tools\\node\\

如果需要配置系统级 Node.js：

步骤 1：打开 File → Settings → HarmonyOS SDK → Node.js
步骤 2：选择 Node.js 路径：
– Use DevEco Studio built-in（推荐）
– Use system Node.js（自定义路径）
步骤 3：点击 Apply

OHPM 配置：

OHPM（OpenHarmony Package Manager）是鸿蒙生态的包管理器，类似于 npm：

// oh-package.json5 – 项目依赖配置示例
{
"name": "myapp",
"version": "1.0.0",
"description": "My HarmonyOS Application",
"main": "",
"author": "",
"license": "",
// 项目依赖
"dependencies": {
"@ohos/axios": "^2.2.0", // HTTP 请求库
"@ohos/crypto-js": "^4.2.0" // 加密工具库
},
// 开发依赖
"devDependencies": {
"@ohos/hypium": "1.0.18" // 单元测试框架
}
}

OHPM 常用命令：

# 安装项目所有依赖
ohpm install

# 安装指定依赖包
ohpm install @ohos/axios

# 安装指定版本的依赖
ohpm install @ohos/axios@2.2.0

# 卸载依赖包
ohpm uninstall @ohos/axios

# 更新所有依赖到最新版本
ohpm update

# 查看已安装的依赖
ohpm list

# 搜索包
ohpm search axios

# 清除缓存
ohpm clean

# 查看全局配置
ohpm config list

# 设置镜像源（加速下载）
ohpm config set registry https://ohpm.openharmony.cn/ohpm/

# 设置代理
ohpm config set proxy http://127.0.0.1:7890

5.5 环境变量配置详解

DevEco Studio 安装时会自动配置以下环境变量。如果需要手动配置或修复：

系统环境变量列表：

手动配置环境变量步骤：

# 方法 1：通过 Windows 图形界面
# 1. 右键"此电脑" → 属性 → 高级系统设置 → 环境变量
# 2. 在"系统变量"或"用户变量"中找到 Path
# 3. 编辑并添加以下路径（根据实际安装路径修改）

# 方法 2：通过 PowerShell 临时设置（仅当前会话有效）
$env:PATH += ";D:\\Huawei\\DevEcoStudio\\tools\\hdc"
$env:PATH += ";D:\\Huawei\\DevEcoStudio\\tools\\node"
$env:PATH += ";D:\\Huawei\\DevEcoStudio\\tools\\ohpm\\bin"
$env:HDC_SERVER_PORT = "7200"

# 方法 3：通过 PowerShell 永久设置
[Environment]::SetEnvironmentVariable("HDC_SERVER_PORT", "7200", "User")
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
$newPath = "$currentPath;D:\\Huawei\\DevEcoStudio\\tools\\hdc;D:\\Huawei\\DevEcoStudio\\tools\\ohpm\\bin"
[Environment]::SetEnvironmentVariable("PATH", $newPath, "User")

5.6 代理与镜像配置

如果网络环境需要代理才能访问外部资源：

DevEco Studio 代理配置：

步骤 1：File → Settings → Appearance & Behavior → System Settings → HTTP Proxy
步骤 2：选择代理类型：
– Auto-detect proxy settings（自动检测）
– No proxy（无代理）
– Manual proxy configuration（手动配置）
步骤 3：手动配置时填写：
– Host name: 127.0.0.1（或代理服务器地址）
– Port number: 7890（或代理端口）
– 如需认证：勾选 "Proxy authentication"，填写用户名和密码
步骤 4：点击 "Check connection" 测试连接
步骤 5：点击 Apply → OK

OHPM 镜像源配置（加速国内下载）：

# 设置 OHPM 使用国内镜像
ohpm config set registry https://ohpm.openharmony.cn/ohpm/

# 或设置代理
ohpm config set proxy http://127.0.0.1:7890

# 查看当前配置
ohpm config list

Hvigor 构建代理配置：

// hvigor/hvigor-config.json5
{
"modelVersion": "5.0.0",
"dependencies": {
"hvigor": "4.2.2",
"@ohos/hvigor-ohos-plugin": "4.2.2"
},
"execution": {
"analyzeMode": "advanced",
"logLevel": "info"
},
"logging": {
// 如需代理下载依赖
"proxy": "http://127.0.0.1:7890"
}
}

六、项目创建与工程结构详解

6.1 创建新项目

创建步骤：

方法 1：通过欢迎界面
Welcome to DevEco Studio → Create Project

方法 2：通过菜单栏
File → New → Create Project

方法 3：快捷键
Ctrl + Shift + N（部分版本支持）

项目创建向导流程：

┌─────────────────────────────────────────────────────┐
│ Create Project │
├─────────────────────────────────────────────────────┤
│ │
│ Choose your project type: │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Empty │ │ List │ │ Tab │ │
│ │ Ability │ │ Ability │ │ Ability │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Atomic │ │ Game │ │ Library │ │
│ │ Service │ │ Template │ │ Module │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ [Next] │
└─────────────────────────────────────────────────────┘

项目配置页面：

Project name: MyApp # 项目名称（英文，无空格）
Bundle name: com.example.myapp # 包名（唯一标识）
Save location: D:\\Projects\\MyApp # 保存路径
Compile SDK: 5.0.0(12) # 编译 SDK 版本
Compatible SDK: 5.0.0(12) # 最低兼容版本
Model: Stage # 项目模型（Stage/FA）
Language: ArkTS # 开发语言

☑ Enable Native C++ Support # 是否启用 Native 支持（可选）

[Finish]

6.2 工程模板类型说明

6.3 项目目录结构详解

以 Empty Ability 模板创建的 Stage 模型项目为例：

MyApp/ # 项目根目录
├── .hvigor/ # Hvigor 构建工具缓存目录
│ └── …
├── .idea/ # IDE 项目配置（勿提交到 Git）
│ ├── codeStyles/ # 代码风格配置
│ ├── inspectionProfiles/ # 代码检查配置
│ └── …
├── AppScope/ # 应用级全局资源目录
│ ├── app.json5 # 应用全局配置文件
│ └── resources/ # 应用级资源文件
│ └── base/
│ ├── element/
│ │ └── string.json # 全局字符串资源
│ └── media/
│ └── app_icon.png # 应用图标
├── entry/ # 默认主模块（入口模块）
│ ├── build/ # 编译构建产物输出目录
│ ├── src/ # 源代码目录
│ │ ├── main/ # 主源代码集
│ │ │ ├── ets/ # ArkTS 源代码
│ │ │ │ ├── entryability/ # Ability 入口
│ │ │ │ │ └── EntryAbility.ets # Ability 生命周期管理
│ │ │ │ ├── pages/ # 页面目录
│ │ │ │ │ └── Index.ets # 首页
│ │ │ │ └── common/ # 公共代码
│ │ │ ├── resources/ # 模块资源文件
│ │ │ │ ├── base/ # 基础资源
│ │ │ │ │ ├── element/ # 元素资源（字符串、颜色等）
│ │ │ │ │ ├── media/ # 媒体资源（图片等）
│ │ │ │ │ └── profile/ # 配置文件
│ │ │ │ │ └── main_pages.json # 页面路由配置
│ │ │ │ ├── en_US/ # 英文资源
│ │ │ │ └── zh_CN/ # 中文资源
│ │ │ └── module.json5 # 模块配置文件（核心）
│ │ └── ohosTest/ # 测试代码
│ │ └── ets/
│ │ └── test/
│ ├── build-profile.json5 # 模块构建配置
│ ├── hvigorfile.ts # 模块构建脚本
│ └── oh-package.json5 # 模块依赖配置
├── build-profile.json5 # 项目级构建配置
├── hvigorfile.ts # 项目级构建脚本
├── hvigor/ # Hvigor 构建工具配置
│ ├── hvigor-config.json5 # Hvigor 版本和依赖配置
│ └── hvigor-wrapper.js # Hvigor 包装脚本
├── oh-package.json5 # 项目级依赖配置
├── oh-package-lock.json5 # 依赖锁定文件
├── node_modules/ # 安装的依赖包（勿提交到 Git）
└── local.properties # 本地环境配置（SDK 路径等）

6.4 关键配置文件解读

6.4.1 app.json5（应用全局配置）

// AppScope/app.json5
{
"app": {
// 应用的 Bundle Name，全局唯一标识符
"bundleName": "com.example.myapp",

// 应用供应商信息
"vendor": "example",

// 应用版本号
"versionCode": 1000000,

// 应用版本名称（展示给用户）
"versionName": "1.0.0",

// 应用图标资源引用
"icon": "$media:app_icon",

// 应用名称资源引用
"label": "$string:app_name",

// 分布式权限声明（如需跨设备能力）
"distributedNotificationEnabled": true,

// 应用支持的最低 API 版本
"minAPIVersion": 12,

// 目标 API 版本
"targetAPIVersion": 12
}
}

6.4.2 module.json5（模块配置 – 核心文件）

// entry/src/main/module.json5
{
"module": {
// 模块名称
"name": "entry",

// 模块类型：entry（入口模块）或 feature（特性模块）
"type": "entry",

// 模块描述
"description": "$string:module_desc",

// 主页面的 Ability 图标
"mainElement": "EntryAbility",

// 设备类型：支持的设备形态
"deviceTypes": [
"phone", // 手机
"tablet", // 平板
"2in1" // 二合一设备
],

// 页面交付物（HAP 包）
"deliveryWithInstall": true,

// 安装后是否自动运行
"installationFree": false,

// 页面路由配置文件
"pages": "$profile:main_pages",

// Ability 配置
"abilities": [
{
// Ability 名称
"name": "EntryAbility",

// Ability 源代码路径
"srcEntry": "./ets/entryability/EntryAbility.ets",

// Ability 描述
"description": "$string:EntryAbility_desc",

// Ability 图标
"icon": "$media:layered_image",

// Ability 标签
"label": "$string:EntryAbility_label",

// 启动类型：singleton（单例）/ multiton（多例）
"launchType": "singleton",

// 是否支持开始窗口
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",

// 是否可被其他应用调用
"exported": true,

// 技能声明（应用入口）
"skills": [
{
"entities": [
"entity.system.home" // 系统主页入口
],
"actions": [
"action.system.home" // 主页 Action
]
}
]
}
],

// 扩展能力配置
"extensionAbilities": [
{
// 服务卡片扩展
"name": "EntryBackupAbility",
"srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
]
}
],

// 权限声明
"requestPermissions": [
{
// 网络访问权限
"name": "ohos.permission.INTERNET"
},
{
// 获取网络状态权限
"name": "ohos.permission.GET_NETWORK_INFO"
}
// 更多权限根据需要添加
]
}
}

6.4.3 main_pages.json（页面路由配置）

// entry/src/main/resources/base/profile/main_pages.json
{
"src": [
"pages/Index",
"pages/SecondPage",
"pages/DetailPage"
]
}

重要：每个新建的页面都必须在此文件中注册，否则运行时将报"页面未找到"错误。

6.4.4 build-profile.json5（构建配置）

// 项目根目录/build-profile.json5
{
"app": {
"signingConfigs": [
{
"name": "default",
"type": "HarmonyOS",
"material": {
// 自动签名时由 IDE 自动填充
"certpath": "",
"storePassword": "",
"keyAlias": "",
"keyPassword": "",
"profile": "",
"signAlg": "SHA256withECDSA",
"storeFile": ""
}
}
],
"products": [
{
"name": "default",
"signingConfig": "default",
// 编译 SDK 版本
"compileSdkVersion": "5.0.0(12)",
// 最低兼容 SDK 版本
"compatibleSdkVersion": "5.0.0(12)",
// 构建选项
"buildOption": {
"strictMode": {
// 大小写敏感检查
"caseSensitiveCheck": true,
// 使用声明式 API 检查
"useNormalizedOHMUrl": true
}
},
// 运行时操作系统兼容版本
"runtimeOS": "HarmonyOS"
}
],
"buildModeSet": [
{ "name": "debug" },
{ "name": "release" }
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
}
]
}
]
}

6.5 多模块工程管理

DevEco Studio 支持在一个项目中包含多个模块：

MyApp/ # 主工程
├── entry/ # 入口模块（HAP）
├── common/ # 公共库模块（HAR）
│ ├── src/main/ets/
│ ├── build-profile.json5
│ └── oh-package.json5
├── feature_home/ # 首页特性模块
│ ├── src/main/ets/
│ └── …
├── feature_profile/ # 个人中心特性模块
│ ├── src/main/ets/
│ └── …
└── build-profile.json5 # 项目级配置（包含所有模块声明）

添加新模块：

File → New → Module → 选择模块类型：
– Application Module (HAP) # 独立应用模块
– Library Module (HAR) # 共享库模块
– Static Library (HSP) # 静态共享库

七、ArkTS 开发实战与代码示例

7.1 ArkTS 语言基础

ArkTS 是 HarmonyOS 的主力开发语言，基于 TypeScript 扩展，增加了声明式 UI 和状态管理等能力。

ArkTS 与 TypeScript 的关系：

ArkTS = TypeScript + 声明式 UI 语法 + 状态管理装饰器 + 系统 API
↓
超集关系，ArkTS 兼容大部分 TypeScript 语法
但增加了更严格的类型约束

基础语法示例：

// ArkTS 基础类型
let userName: string = "鸿蒙开发者" // 字符串
let age: number = 25 // 数字
let isDeveloper: boolean = true // 布尔值
let skills: string[] = ["ArkTS", "ArkUI"] // 数组

// 接口定义
interface UserInfo {
name: string
age: number
email?: string // 可选属性
}

// 枚举定义
enum ThemeMode {
Light,
Dark,
Auto
}

// 函数定义
function greet(name: string, greeting: string = "你好"): string {
return `${greeting}, ${name}!`
}

// 箭头函数
const add = (a: number, b: number): number => a + b

// 类定义
class User {
private _name: string
private _age: number

constructor(name: string, age: number) {
this._name = name
this._age = age
}

// Getter
get name(): string {
return this._name
}

// 方法
introduce(): string {
return `我叫${this._name}，今年${this._age}岁`
}
}

7.2 声明式 UI 开发

ArkUI 使用声明式语法描述 UI，开发者只需描述"UI 应该是什么样子"，框架负责渲染和更新。

基础页面示例（Index.ets）：

// entry/src/main/ets/pages/Index.ets

// 使用 @Entry 装饰器标记为入口页面
// 使用 @Component 装饰器标记为自定义组件
@Entry
@Component
struct Index {
// 状态变量：当值改变时，UI 会自动重新渲染
@State message: string = 'Hello HarmonyOS'
@State count: number = 0
@State fontSize: number = 24

// 页面构建方法 – 描述 UI 结构
build() {
// 根容器 – Column 垂直布局
Column() {
// 文本组件
Text(this.message)
.fontSize(this.fontSize) // 字体大小
.fontWeight(FontWeight.Bold) // 字体粗细
.fontColor('#333333') // 字体颜色
.margin({ top: 50 }) // 外边距

// 图片组件
Image($r('app.media.app_icon')) // 引用资源文件中的图片
.width(100) // 宽度
.height(100) // 高度
.borderRadius(50) // 圆角（圆形头像效果）
.margin({ top: 20, bottom: 30 }) // 外边距

// 计数器显示
Text(`点击次数: ${this.count}`)
.fontSize(20)
.fontColor('#666666')
.margin({ bottom: 20 })

// 按钮组件
Button('点击 +1')
.type(ButtonType.Capsule) // 胶囊型按钮
.width('60%') // 宽度百分比
.height(50) // 高度
.fontSize(18) // 字体大小
.backgroundColor('#007DFF') // 背景色（华为蓝）
.onClick(() => {
// 点击事件处理
this.count++
// 每点击 5 次改变字体大小
if (this.count % 5 === 0) {
this.fontSize = this.fontSize === 24 ? 32 : 24
}
})

// 输入框组件
TextInput({ placeholder: '请输入您的名字', text: '' })
.width('80%')
.height(48)
.margin({ top: 20 })
.onChange((value: string) => {
// 输入内容变化时更新消息
this.message = `Hello, ${value || 'HarmonyOS'}!`
})
}
.width('100%') // 容器宽度占满
.height('100%') // 容器高度占满
.justifyContent(FlexAlign.Start) // 垂直方向对齐方式
.alignItems(HorizontalAlign.Center) // 水平居中对齐
}
}

列表页面示例：

// entry/src/main/ets/pages/ListPage.ets

// 数据模型
interface TodoItem {
id: number
title: string
completed: boolean
priority: 'high' | 'medium' | 'low'
}

@Entry
@Component
struct ListPage {
// 待办事项列表
@State todoList: TodoItem[] = [
{ id: 1, title: '学习 ArkTS 基础语法', completed: true, priority: 'high' },
{ id: 2, title: '掌握 ArkUI 组件使用', completed: false, priority: 'high' },
{ id: 3, title: '了解状态管理机制', completed: false, priority: 'medium' },
{ id: 4, title: '学习页面路由导航', completed: false, priority: 'medium' },
{ id: 5, title: '实践网络请求', completed: false, priority: 'low' }
]

// 新任务输入
@State newTaskTitle: string = ''

// 添加任务方法
addTask(): void {
if (this.newTaskTitle.trim().length === 0) return

const newTask: TodoItem = {
id: Date.now(),
title: this.newTaskTitle.trim(),
completed: false,
priority: 'medium'
}
this.todoList.push(newTask)
this.newTaskTitle = ''
}

// 删除任务方法
deleteTask(index: number): void {
this.todoList.splice(index, 1)
}

// 切换完成状态
toggleComplete(index: number): void {
this.todoList[index].completed = !this.todoList[index].completed
}

build() {
Column() {
// 标题栏
Text('待办清单')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.margin({ top: 16, bottom: 16 })

// 输入区域
Row() {
TextInput({ placeholder: '添加新任务…', text: this.newTaskTitle })
.layoutWeight(1)
.height(40)
.onChange((value: string) => {
this.newTaskTitle = value
})

Button('添加')
.type(ButtonType.Normal)
.height(40)
.margin({ left: 8 })
.backgroundColor('#007DFF')
.onClick(() => this.addTask())
}
.width('90%')
.padding(12)

// 列表区域
List({ space: 8 }) {
ForEach(this.todoList, (item: TodoItem, index: number) => {
ListItem() {
Row() {
// 完成状态复选框
Checkbox()
.select(item.completed)
.selectedColor('#007DFF')
.onChange((checked: boolean) => {
this.toggleComplete(index)
})

// 任务标题
Text(item.title)
.fontSize(16)
.fontColor(item.completed ? '#999999' : '#333333')
.decoration({
type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None
})
.layoutWeight(1)
.margin({ left: 12 })

// 优先级标签
Text(item.priority === 'high' ? '高' : item.priority === 'medium' ? '中' : '低')
.fontSize(12)
.fontColor('#FFFFFF')
.backgroundColor(
item.priority === 'high' ? '#FF4444' :
item.priority === 'medium' ? '#FFAA00' : '#44BB44'
)
.borderRadius(4)
.padding({ left: 6, right: 6, top: 2, bottom: 2 })

// 删除按钮
Image($r('sys.media.ohos_ic_public_delete'))
.width(24)
.height(24)
.margin({ left: 12 })
.onClick(() => this.deleteTask(index))
}
.width('100%')
.padding(12)
.backgroundColor('#F5F5F5')
.borderRadius(8)
}
}, (item: TodoItem) => item.id.toString())
}
.width('100%')
.layoutWeight(1)
.padding({ left: 16, right: 16 })

// 底部统计
Row() {
Text(`总计: ${this.todoList.length} 项`)
.fontSize(14)
.fontColor('#999999')
Blank()
Text(`已完成: ${this.todoList.filter(item => item.completed).length} 项`)
.fontSize(14)
.fontColor('#007DFF')
}
.width('90%')
.padding({ top: 12, bottom: 12 })
}
.width('100%')
.height('100%')
}
}

7.3 状态管理详解

ArkTS 提供了丰富的状态管理装饰器：

// entry/src/main/ets/pages/StateDemo.ets

// ============================================
// 数据模型类
// ============================================
@Observed
class UserModel {
name: string
age: number
avatar: string

constructor(name: string, age: number, avatar: string) {
this.name = name
this.age = age
this.avatar = avatar
}
}

// ============================================
// 子组件 – 展示用户信息
// ============================================
@Component
struct UserInfoCard {
// @ObjectLink 用于接收父组件传递的 @Observed 对象
// 当对象属性变化时，子组件会自动更新
@ObjectLink user: UserModel

// @Prop 单向数据流：父 → 子
// 子组件的修改不会影响父组件
@Prop showAge: boolean = true

// @Event 自定义事件回调
onNameClick?: () => void

build() {
Row() {
// 头像
Image($r(this.user.avatar))
.width(60)
.height(60)
.borderRadius(30)

Column() {
Text(this.user.name)
.fontSize(18)
.fontWeight(FontWeight.Bold)
.onClick(() => {
// 触发回调事件
if (this.onNameClick) {
this.onNameClick()
}
})

if (this.showAge) {
Text(`年龄: ${this.user.age}`)
.fontSize(14)
.fontColor('#666666')
.margin({ top: 4 })
}
}
.alignItems(HorizontalAlign.Start)
.margin({ left: 16 })
.layoutWeight(1)
}
.width('100%')
.padding(16)
.backgroundColor('#FFFFFF')
.borderRadius(12)
.shadow({ radius: 4, color: '#1A000000', offsetY: 2 })
}
}

// ============================================
// 主页面
// ============================================
@Entry
@Component
struct StateDemo {
// @State：组件自身状态，变化时触发 UI 重新渲染
@State counter: number = 0
@State inputText: string = ''
@State isVisible: boolean = true

// @State + @Observed：观察对象属性变化
@State user: UserModel = new UserModel('张三', 28, 'app.media.app_icon')

// @Provide：向子孙组件提供状态（跨层级传递）
@Provide('theme') themeColor: string = '#007DFF'

// @StorageLink：与 AppStorage 双向绑定（全局状态）
@StorageLink('userName') globalUserName: string = ''

// 生命周期 – 页面创建时调用
aboutToAppear(): void {
console.info('StateDemo: aboutToAppear')
// 初始化数据、发起网络请求等
}

// 生命周期 – 页面销毁时调用
aboutToDisappear(): void {
console.info('StateDemo: aboutToDisappear')
// 清理资源、取消订阅等
}

build() {
Scroll() {
Column({ space: 16 }) {
// 标题
Text('状态管理示例')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.margin({ top: 20 })

// 计数器区域
Column() {
Text(`${this.counter}`)
.fontSize(48)
.fontWeight(FontWeight.Bold)
.fontColor(this.themeColor)

Row({ space: 16 }) {
Button('-1')
.onClick(() => { this.counter— })

Button('重置')
.onClick(() => { this.counter = 0 })

Button('+1')
.onClick(() => { this.counter++ })
}
}
.padding(20)
.backgroundColor('#F5F5F5')
.borderRadius(12)
.width('90%')

// 用户信息卡片（使用子组件）
UserInfoCard({
user: this.user,
showAge: this.isVisible,
onNameClick: () => {
// 点击名字时修改用户信息
this.user.name = this.user.name === '张三' ? '李四' : '张三'
}
})

// 输入框（双向绑定示例）
TextInput({ placeholder: '请输入全局用户名', text: this.globalUserName })
.width('90%')
.height(48)
.onChange((value: string) => {
this.globalUserName = value
})

// 显示/隐藏切换
Toggle({ type: ToggleType.Switch, isOn: this.isVisible })
.selectedColor(this.themeColor)
.onChange((isOn: boolean) => {
this.isVisible = isOn
})

Text(this.isVisible ? '显示年龄信息' : '隐藏年龄信息')
.fontSize(14)
.fontColor('#666666')
}
.width('100%')
.alignItems(HorizontalAlign.Center)
.padding({ bottom: 40 })
}
.width('100%')
.height('100%')
}
}

状态管理装饰器速查：

7.4 页面路由与导航

// entry/src/main/ets/pages/Index.ets
// 首页 – 路由导航示例

import { router } from '@kit.ArkUI'

@Entry
@Component
struct Index {
@State menuItems: Array<{ title: string, desc: string, page: string }> = [
{ title: '基础组件', desc: 'Text, Image, Button 等基础 UI 组件', page: 'pages/BasicComponents' },
{ title: '列表展示', desc: 'List, ForEach, LazyForEach 列表组件', page: 'pages/ListDemo' },
{ title: '网络请求', desc: 'HTTP 请求与数据展示', page: 'pages/NetworkDemo' },
{ title: '数据持久化', desc: 'Preferences 与 SQLite 存储', page: 'pages/StorageDemo' }
]

build() {
Column() {
// 顶部标题栏
Row() {
Text('鸿蒙学习中心')
.fontSize(22)
.fontWeight(FontWeight.Bold)
.fontColor('#FFFFFF')
}
.width('100%')
.height(56)
.backgroundColor('#007DFF')
.justifyContent(FlexAlign.Center)

// 列表菜单
List({ space: 12 }) {
ForEach(this.menuItems, (item: { title: string, desc: string, page: string }) => {
ListItem() {
Row() {
Column() {
Text(item.title)
.fontSize(18)
.fontWeight(FontWeight.Medium)

Text(item.desc)
.fontSize(13)
.fontColor('#999999')
.margin({ top: 4 })
.maxLines(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
}
.alignItems(HorizontalAlign.Start)
.layoutWeight(1)

Image($r('sys.media.ohos_ic_public_arrow_right'))
.width(20)
.height(20)
}
.width('100%')
.padding(16)
.backgroundColor('#FFFFFF')
.borderRadius(8)
.onClick(() => {
// 路由跳转到指定页面
router.pushUrl({
url: item.page,
params: {
title: item.title // 传递参数
}
})
})
}
})
}
.width('100%')
.layoutWeight(1)
.padding(16)
}
.width('100%')
.height('100%')
.backgroundColor('#F0F0F0')
}
}

// entry/src/main/ets/pages/BasicComponents.ets
// 子页面 – 接收路由参数并展示

import { router } from '@kit.ArkUI'

@Entry
@Component
struct BasicComponents {
@State pageTitle: string = ''

aboutToAppear(): void {
// 获取路由传递的参数
const params = router.getParams() as Record<string, string>
if (params && params['title']) {
this.pageTitle = params['title']
}
}

build() {
Column() {
// 顶部导航栏（含返回按钮）
Row() {
Image($r('sys.media.ohos_ic_public_arrow_left'))
.width(24)
.height(24)
.fillColor('#FFFFFF')
.onClick(() => {
// 返回上一页
router.back()
})

Text(this.pageTitle)
.fontSize(18)
.fontWeight(FontWeight.Bold)
.fontColor('#FFFFFF')
.margin({ left: 12 })
}
.width('100%')
.height(56)
.backgroundColor('#007DFF')
.padding({ left: 16, right: 16 })

// 页面内容
Scroll() {
Column({ space: 16 }) {
// 示例：各种基础组件展示
// … 此处省略具体组件展示代码
Text('基础组件示例页面')
.fontSize(16)
.margin({ top: 20 })
}
.width('100%')
.padding(16)
}
.layoutWeight(1)
}
.width('100%')
.height('100%')
}
}

7.5 网络请求与数据展示

// entry/src/main/ets/pages/NetworkDemo.ets
// 网络请求示例页面

import { http } from '@kit.NetworkKit'

// API 响应数据模型
interface ApiResponse {
code: number
message: string
data: NewsItem[]
}

interface NewsItem {
id: number
title: string
summary: string
imageUrl: string
publishTime: string
category: string
}

@Entry
@Component
struct NetworkDemo {
@State newsList: NewsItem[] = []
@State isLoading: boolean = false
@State errorMessage: string = ''
@State isRefreshing: boolean = false

aboutToAppear(): void {
this.fetchNews()
}

// 发起网络请求
async fetchNews(): Promise<void> {
this.isLoading = true
this.errorMessage = ''

try {
// 创建 HTTP 请求
const httpRequest = http.createHttp()

// 发起 GET 请求
const response = await httpRequest.request(
'https://api.example.com/news',
{
method: http.RequestMethod.GET,
header: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your_token_here'
},
connectTimeout: 10000, // 连接超时 10 秒
readTimeout: 15000, // 读取超时 15 秒
expectDataType: http.HttpDataType.STRING
}
)

// 处理响应
if (response.responseCode === http.ResponseCode.OK) {
const result: ApiResponse = JSON.parse(response.result as string)
if (result.code === 200) {
this.newsList = result.data
} else {
this.errorMessage = `请求失败: ${result.message}`
}
} else {
this.errorMessage = `HTTP 错误: ${response.responseCode}`
}

// 销毁请求实例
httpRequest.destroy()
} catch (error) {
const err = error as Error
this.errorMessage = `网络异常: ${err.message}`
console.error(`请求失败: ${err.message}`)
} finally {
this.isLoading = false
this.isRefreshing = false
}
}

build() {
Column() {
// 标题栏
Row() {
Text('新闻资讯')
.fontSize(20)
.fontWeight(FontWeight.Bold)
.fontColor('#FFFFFF')

Blank()

// 刷新按钮
Image($r('sys.media.ohos_ic_public_refresh'))
.width(24)
.height(24)
.fillColor('#FFFFFF')
.onClick(() => {
this.isRefreshing = true
this.fetchNews()
})
}
.width('100%')
.height(56)
.backgroundColor('#007DFF')
.padding({ left: 16, right: 16 })

// 加载状态
if (this.isLoading && this.newsList.length === 0) {
Column() {
LoadingProgress()
.width(48)
.height(48)
.color('#007DFF')
Text('加载中…')
.fontSize(14)
.fontColor('#999999')
.margin({ top: 12 })
}
.width('100%')
.layoutWeight(1)
.justifyContent(FlexAlign.Center)
}
// 错误状态
else if (this.errorMessage.length > 0) {
Column() {
Image($r('sys.media.ohos_ic_public_error'))
.width(64)
.height(64)
.fillColor('#FF4444')
Text(this.errorMessage)
.fontSize(14)
.fontColor('#666666')
.margin({ top: 12 })
Button('重新加载')
.margin({ top: 16 })
.onClick(() => this.fetchNews())
}
.width('100%')
.layoutWeight(1)
.justifyContent(FlexAlign.Center)
}
// 数据列表
else {
List({ space: 12 }) {
ForEach(this.newsList, (item: NewsItem) => {
ListItem() {
Row() {
// 新闻图片
Image(item.imageUrl)
.width(80)
.height(80)
.borderRadius(8)
.objectFit(ImageFit.Cover)

Column() {
Text(item.title)
.fontSize(16)
.fontWeight(FontWeight.Medium)
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })

Text(item.summary)
.fontSize(13)
.fontColor('#999999')
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
.margin({ top: 6 })

Row() {
Text(item.category)
.fontSize(11)
.fontColor('#007DFF')
.backgroundColor('#E8F0FF')
.borderRadius(4)
.padding({ left: 6, right: 6, top: 2, bottom: 2 })

Blank()

Text(item.publishTime)
.fontSize(11)
.fontColor('#CCCCCC')
}
.width('100%')
.margin({ top: 8 })
}
.layoutWeight(1)
.margin({ left: 12 })
.alignItems(HorizontalAlign.Start)
}
.width('100%')
.padding(12)
.backgroundColor('#FFFFFF')
.borderRadius(8)
}
})
}
.width('100%')
.layoutWeight(1)
.padding(16)
}
}
.width('100%')
.height('100%')
.backgroundColor('#F5F5F5')
}
}

7.6 完整项目实战示例——天气查询应用

// entry/src/main/ets/common/WeatherModel.ets
// 天气数据模型定义

/**
* 天气信息接口
* 用于描述一个城市的天气数据
*/
export interface WeatherInfo {
city: string // 城市名称
temperature: number // 当前温度（摄氏度）
weatherDesc: string // 天气描述（晴、多云、雨等）
humidity: number // 湿度百分比
windSpeed: number // 风速（km/h）
windDirection: string // 风向
iconCode: string // 天气图标代码
updateTime: string // 更新时间
forecast: ForecastItem[] // 未来天气预报
}

/**
* 天气预报接口
* 用于描述某一天的天气预报
*/
export interface ForecastItem {
date: string // 日期
dayDesc: string // 白天天气
nightDesc: string // 夜间天气
highTemp: number // 最高温度
lowTemp: number // 最低温度
}

/**
* 默认天气数据（用于初始展示和模拟）
*/
export function getDefaultWeather(): WeatherInfo {
return {
city: '北京',
temperature: 26,
weatherDesc: '晴',
humidity: 45,
windSpeed: 12,
windDirection: '东南风',
iconCode: 'sunny',
updateTime: '刚刚更新',
forecast: [
{ date: '明天', dayDesc: '多云', nightDesc: '阴', highTemp: 28, lowTemp: 18 },
{ date: '后天', dayDesc: '小雨', nightDesc: '中雨', highTemp: 22, lowTemp: 15 },
{ date: '周五', dayDesc: '阴', nightDesc: '多云', highTemp: 25, lowTemp: 16 },
{ date: '周六', dayDesc: '晴', nightDesc: '晴', highTemp: 30, lowTemp: 20 },
{ date: '周日', dayDesc: '多云', nightDesc: '阴', highTemp: 27, lowTemp: 19 }
]
}
}

// entry/src/main/ets/common/WeatherService.ets
// 天气数据服务

import { http } from '@kit.NetworkKit'
import { WeatherInfo, getDefaultWeather } from './WeatherModel'

/**
* 天气服务类
* 封装天气数据的网络请求和模拟逻辑
*/
export class WeatherService {
// API 基础地址（实际开发时替换为真实 API）
private static readonly BASE_URL = 'https://api.example.com/weather'

/**
* 查询指定城市的天气
* @param city 城市名称
* @returns 天气信息
*/
static async queryWeather(city: string): Promise<WeatherInfo> {
try {
const httpRequest = http.createHttp()

const response = await httpRequest.request(
`${WeatherService.BASE_URL}?city=${encodeURIComponent(city)}`,
{
method: http.RequestMethod.GET,
header: {
'Content-Type': 'application/json'
},
connectTimeout: 8000,
readTimeout: 10000
}
)

httpRequest.destroy()

if (response.responseCode === http.ResponseCode.OK) {
// 解析真实 API 响应（此处为示例结构）
const data = JSON.parse(response.result as string)
return {
city: city,
temperature: data.temp || 25,
weatherDesc: data.weather || '晴',
humidity: data.humidity || 50,
windSpeed: data.windSpeed || 10,
windDirection: data.windDir || '微风',
iconCode: data.iconCode || 'sunny',
updateTime: new Date().toLocaleTimeString('zh-CN'),
forecast: data.forecast || getDefaultWeather().forecast
}
}
} catch (error) {
console.warn(`天气查询失败，使用默认数据: ${(error as Error).message}`)
}

// 网络失败时返回模拟数据（开发阶段）
const defaultWeather = getDefaultWeather()
defaultWeather.city = city
defaultWeather.updateTime = '离线数据'
return defaultWeather
}
}

// entry/src/main/ets/pages/WeatherApp.ets
// 天气查询应用主页面

import { WeatherInfo, getDefaultWeather } from '../common/WeatherModel'
import { WeatherService } from '../common/WeatherService'

@Entry
@Component
struct WeatherApp {
// 天气数据状态
@State weatherData: WeatherInfo = getDefaultWeather()
@State searchCity: string = ''
@State isLoading: boolean = false
@State errorMessage: string = ''

// 热门搜索城市
private hotCities: string[] = ['北京', '上海', '广州', '深圳', '杭州', '成都']

/**
* 查询天气
*/
async searchWeather(): Promise<void> {
const city = this.searchCity.trim()
if (city.length === 0) {
this.errorMessage = '请输入城市名称'
return
}

this.isLoading = true
this.errorMessage = ''

try {
this.weatherData = await WeatherService.queryWeather(city)
} catch (error) {
this.errorMessage = `查询失败: ${(error as Error).message}`
} finally {
this.isLoading = false
}
}

/**
* 获取天气背景渐变色
*/
getBackgroundGradient(): string {
const temp = this.weatherData.temperature
if (temp >= 35) return '#FF6B35' // 高温 – 橙红
if (temp >= 28) return '#FFB347' // 炎热 – 橙色
if (temp >= 20) return '#4ECDC4' // 舒适 – 青绿
if (temp >= 10) return '#45B7D1' // 凉爽 – 蓝色
return '#6C5CE7' // 寒冷 – 紫色
}

build() {
Column() {
// ===== 搜索区域 =====
Row() {
TextInput({ placeholder: '输入城市名查询天气', text: this.searchCity })
.layoutWeight(1)
.height(40)
.backgroundColor('#F0F0F0')
.borderRadius(20)
.padding({ left: 16, right: 16 })
.onChange((value: string) => {
this.searchCity = value
})
.onSubmit(() => {
this.searchWeather()
})

Button('查询')
.type(ButtonType.Normal)
.height(40)
.margin({ left: 8 })
.borderRadius(20)
.backgroundColor('#007DFF')
.enabled(!this.isLoading)
.onClick(() => this.searchWeather())
}
.width('90%')
.padding({ top: 16 })

// ===== 热门城市标签 =====
Flex({ wrap: FlexWrap.Wrap, justifyContent: FlexAlign.Center }) {
ForEach(this.hotCities, (city: string) => {
Text(city)
.fontSize(13)
.fontColor('#666666')
.backgroundColor('#F0F0F0')
.borderRadius(16)
.padding({ left: 12, right: 12, top: 6, bottom: 6 })
.margin(4)
.onClick(() => {
this.searchCity = city
this.searchWeather()
})
})
}
.width('90%')
.margin({ top: 12 })

// ===== 加载状态 =====
if (this.isLoading) {
LoadingProgress()
.width(48)
.height(48)
.color('#007DFF')
.margin({ top: 40 })
}
// ===== 错误提示 =====
else if (this.errorMessage.length > 0) {
Text(this.errorMessage)
.fontSize(14)
.fontColor('#FF4444')
.margin({ top: 20 })
}
// ===== 天气信息展示 =====
else {
Scroll() {
Column({ space: 16 }) {
// 当前天气卡片
Column() {
Text(this.weatherData.city)
.fontSize(20)
.fontColor('#FFFFFF')

Text(`${this.weatherData.temperature}°`)
.fontSize(72)
.fontWeight(FontWeight.Thin)
.fontColor('#FFFFFF')
.margin({ top: 8 })

Text(this.weatherData.weatherDesc)
.fontSize(18)
.fontColor('#FFFFFF')
.margin({ top: 4 })

Text(`${this.weatherData.windDirection} ${this.weatherData.windSpeed}km/h | 湿度 ${this.weatherData.humidity}%`)
.fontSize(13)
.fontColor('#CCFFFFFF')
.margin({ top: 12 })

Text(this.weatherData.updateTime)
.fontSize(11)
.fontColor('#99FFFFFF')
.margin({ top: 4 })
}
.width('90%')
.padding(24)
.borderRadius(16)
.linearGradient({
angle: 135,
colors: [
[this.getBackgroundGradient(), 0],
['#2C3E50', 1]
]
})
.margin({ top: 20 })

// 未来天气预报
Column() {
Text('未来天气')
.fontSize(16)
.fontWeight(FontWeight.Medium)
.margin({ bottom: 12 })

ForEach(this.weatherData.forecast, (item: {
date: string, dayDesc: string, nightDesc: string,
highTemp: number, lowTemp: number
}) => {
Row() {
Text(item.date)
.fontSize(14)
.width(50)

Text(item.dayDesc)
.fontSize(14)
.fontColor('#666666')
.layoutWeight(1)

Text(`${item.lowTemp}° / ${item.highTemp}°`)
.fontSize(14)
.fontColor('#333333')
}
.width('100%')
.padding({ top: 10, bottom: 10 })
})
}
.width('90%')
.padding(16)
.backgroundColor('#FFFFFF')
.borderRadius(12)
}
.width('100%')
.alignItems(HorizontalAlign.Center)
.padding({ bottom: 40 })
}
.layoutWeight(1)
}
}
.width('100%')
.height('100%')
.backgroundColor('#F5F5F5')
}
}

八、调试与运行

8.1 模拟器（Emulator）配置与使用

前置条件：

• BIOS 中已开启 CPU 虚拟化（Intel VT-x / AMD-V）
• 已安装模拟器组件（通过 SDK Manager）
• 内存 ≥ 8GB（推荐分配 4GB 给模拟器）
• 预留 10GB+ 磁盘空间

配置步骤：

步骤 1：打开设备管理器
菜单 → Tools → Device Manager
或点击 IDE 右上角的设备图标

步骤 2：创建新模拟器
点击 "+" 按钮 → "Create Virtual Device"

步骤 3：选择设备类型
├── Phone – 手机模拟器（如 P60 Pro 模板）
├── Tablet – 平板模拟器
├── Wearable – 穿戴设备模拟器
└── TV – 智慧屏模拟器

步骤 4：选择系统镜像
选择 HarmonyOS NEXT 对应的系统镜像版本

步骤 5：配置模拟器参数
– RAM: 4096 MB（推荐）
– Internal Storage: 8192 MB
– SD Card: 1024 MB（可选）

步骤 6：完成创建并启动
点击 "Finish" → 选择模拟器 → 点击 ▶ 启动

模拟器控制：

8.2 真机调试配置

使用 USB 连接真机调试：

步骤 1：在手机上开启开发者模式
设置 → 关于手机 → 连续点击 7 次"HarmonyOS 版本号"
→ 提示"您已处于开发者模式"

步骤 2：开启 USB 调试
设置 → 系统和更新 → 开发人员选项
→ 打开 "USB 调试"
→ 打开 "仅充电模式下允许 HDB 连接设备"

步骤 3：USB 连接电脑
使用数据线连接手机和电脑
手机上弹出"允许 HDB 连接"时点击"允许"

步骤 4：验证设备连接
在 DevEco Studio 终端中执行：
hdc list targets
预期输出类似：
设备序列号 device

步骤 5：选择设备运行
在 IDE 顶部的设备选择器中选择你的真机设备
点击 ▶ Run 按钮运行应用

HDC 工具常用命令：

# 查看连接的设备列表
hdc list targets

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

# 卸载应用
hdc uninstall com.example.myapp

# 查看设备日志
hdc hilog

# 过滤特定标签的日志
hdc hilog | grep "MyApp"

# 推送文件到设备
hdc file send local_file.txt /data/local/tmp/

# 从设备拉取文件
hdc file recv /data/local/tmp/log.txt ./log.txt

# 截图
hdc shell snapshot_display -f /data/local/tmp/screenshot.png
hdc file recv /data/local/tmp/screenshot.png ./screenshot.png

# 重启设备
hdc shell reboot

# 启动指定 Ability
hdc shell aa start -a EntryAbility -b com.example.myapp

# 停止指定应用
hdc shell aa force-stop com.example.myapp

8.3 预览器（Previewer）使用

预览器可以在不运行模拟器或真机的情况下，实时预览 UI 效果：

使用方法：

1. 打开任意 .ets 页面文件

2. 在编辑器右侧找到 "Preview" 面板
（如果没有显示，通过菜单 View → Tool Windows → Previewer 打开）

3. 预览器自动渲染当前页面的 UI

4. 修改代码后预览器自动刷新（热更新）

5. 切换预览设备：
– 在预览器顶部选择不同的设备模型
– Phone / Tablet / Foldable / Wearable

6. 交互预览：
– 可以直接在预览器中点击按钮、输入文字等
– 注意：部分功能（如网络请求）在预览器中不可用

预览器限制：预览器不支持完整的运行时环境，涉及系统 API 调用（如权限请求、网络通信、文件存储等）的功能需要模拟器或真机测试。

8.4 断点调试与日志输出

断点调试：

1. 设置断点
– 在代码行号左侧的灰色区域点击，出现红色圆点即为断点
– 右键断点可以设置条件断点（Conditional Breakpoint）

2. 启动调试模式
– 点击 IDE 顶部的 🪲（Debug）按钮
– 或按快捷键 Shift + F9

3. 调试控制面板
├── Step Over (F8) – 单步执行（不进入函数）
├── Step Into (F7) – 单步执行（进入函数）
├── Step Out (Shift+F8) – 跳出当前函数
├── Resume (F9) – 继续执行到下一个断点
├── Stop – 停止调试
├── Variables – 查看当前变量值
├── Watches – 监视表达式
├── Call Stack – 调用栈
└── Breakpoints – 断点管理

日志输出：

// 使用 hilog 输出日志
import { hilog } from '@kit.PerformanceAnalysisKit'

// 定义日志域和标签
const DOMAIN = 0x0001
const TAG = 'MyApp'

// 不同级别的日志
hilog.debug(DOMAIN, TAG, '调试信息: %{public}s', '变量值')
hilog.info(DOMAIN, TAG, '普通信息: %{public}d', 42)
hilog.warn(DOMAIN, TAG, '警告信息: %{public}s', '网络超时')
hilog.error(DOMAIN, TAG, '错误信息: %{public}s', '空指针异常')
hilog.fatal(DOMAIN, TAG, '致命错误: %{public}s', '系统崩溃')

// 注意：
// %{public}s – 公开字符串参数（在日志中可见）
// %{private}s – 私有字符串参数（在日志中脱敏显示）
// %{public}d – 公开整数参数

8.5 性能分析工具

DevEco Studio 内置了多种性能分析工具：

打开方式：View → Tool Windows → Profiler

性能分析类型：
├── CPU Profiler – CPU 使用率和函数调用分析
├── Memory Profiler – 内存使用分析（堆内存、泄漏检测）
├── Frame Profiler – 帧率分析（UI 流畅度）
├── Network Profiler – 网络请求分析
└── ArkWeb Profiler – Web 组件性能分析

使用流程：
1. 连接设备或启动模拟器
2. 运行应用
3. 打开 Profiler 面板
4. 选择分析类型
5. 点击 Record 开始录制
6. 操作应用
7. 点击 Stop 停止录制
8. 分析性能数据

九、签名、打包与发布

9.1 调试证书与发布证书

HarmonyOS 应用采用基于数字证书的安全签名机制，与 Android 的 APK 签名体系有本质区别。每个应用必须经过签名才能安装和运行。

签名体系核心概念：

HarmonyOS 签名体系
├── 密钥（Key）
│ ├── 格式：.p12（PKCS#12 密钥库文件）
│ ├── 作用：存储非对称加密的密钥对（公钥 + 私钥）
│ ├── 创建方式：通过 DevEco Studio 生成
│ └── 注意：密钥文件务必妥善备份，丢失后无法恢复
│
├── 证书请求文件（CSR）
│ ├── 格式：.csr
│ ├── 作用：向华为 CA 申请数字证书
│ └── 创建方式：通过 DevEco Studio 从密钥库导出
│
├── 数字证书（Certificate）
│ ├── 格式：.cer
│ ├── 类型：
│ │ ├── 调试证书（Debug）：用于开发调试，绑定调试设备
│ │ └── 发布证书（Release）：用于应用上架发布
│ └── 获取方式：华为 AppGallery Connect 签发
│
└── Profile 文件
├── 格式：.p7b
├── 类型：
│ ├── 调试 Profile：绑定设备 UDID、指定调试权限
│ └── 发布 Profile：指定发布权限和分发信息
├── 作用：关联证书、应用包名、设备信息、权限声明
└── 获取方式：华为 AppGallery Connect 申请

签名类型对比：

9.2 自动签名配置

DevEco Studio 为调试场景提供了便捷的自动签名功能：

自动签名配置步骤：

步骤 1：确保已登录华为开发者账号
点击 IDE 右上角的"Login"按钮
使用华为开发者账号登录

步骤 2：打开项目签名设置
File → Project Structure → Project → Signing Configs

步骤 3：勾选 "Automatically generate signature"
☑ Automatically generate signature

步骤 4：IDE 自动完成以下操作
├── 自动生成密钥库文件（.p12）
├── 自动生成证书请求文件（.csr）
├── 向华为 CA 申请调试证书（.cer）
├── 申请调试 Profile 文件（.p7b）
└── 自动填充签名配置信息

步骤 5：等待自动签名完成（约 10-30 秒）
完成后可以看到所有签名信息已自动填充

步骤 6：点击 "Apply" → "OK"

自动签名的限制：

以下场景必须使用手动签名：

❌ 跨设备调试（调试设备不在已绑定列表中）
❌ 跨应用交互调试
❌ 断网情况下调试（自动签名需要网络）
❌ 多开发者共享密钥
❌ 使用受限开放权限（部分 ACL 权限不支持自动签名）
❌ 应用发布上架

自动签名生成的文件位置：

项目根目录/
└── entry/
└── src/
└── main/
└── signing/ # 自动签名生成的文件目录
├── debug/
│ ├── internal/
│ │ ├── auto_sign.p12 # 密钥库文件
│ │ ├── auto_sign.csr # 证书请求文件
│ │ ├── auto_sign.cer # 调试证书
│ │ └── auto_sign.p7b # Profile 文件
│ └── …
└── release/ # 发布签名（需手动配置）

9.3 手动签名配置

手动签名需要开发者在 AppGallery Connect 上申请证书和 Profile 文件：

步骤 1：生成密钥库和证书请求文件

步骤 1.1：File → Project Structure → Project → Signing Configs

步骤 1.2：取消勾选 "Automatically generate signature"

步骤 1.3：点击 "Store file" 右侧的 "…" 按钮
选择 "Create new keystore"

步骤 1.4：填写密钥库信息
├── Key store file: D:\\MyApp\\keystore\\myapp_release.p12
├── Key store password: YourStrongPassword123!
├── Key alias: myapp_key
└── Key password: YourKeyPassword123!

步骤 1.5：点击 "OK" 生成密钥库文件

步骤 1.6：生成 CSR 文件
点击 "Generate CSR" 按钮
保存 CSR 文件到本地

步骤 2：在 AppGallery Connect 申请证书

步骤 2.1：登录 AppGallery Connect
https://developer.huawei.com/consumer/cn/service/josp/agc/index.html

步骤 2.2：进入 "用户与访问" → "证书管理"

步骤 2.3：点击 "新增证书"
├── 选择证书类型：发布证书 / 调试证书
├── 上传 CSR 文件
└── 点击 "提交"

步骤 2.4：下载证书文件（.cer）

步骤 3：申请 Profile 文件

步骤 3.1：在 AppGallery Connect 中进入 "我的项目"

步骤 3.2：选择你的项目 → "HarmonyOS" → "HarmonyOS应用"

步骤 3.3：进入 "项目管理" → "Profile管理"

步骤 3.4：点击 "新增Profile"
├── 选择证书（刚才申请的证书）
├── 选择应用包名（Bundle Name）
├── 选择设备（调试证书需绑定设备 UDID）
├── 选择权限
└── 点击 "提交"

步骤 3.5：下载 Profile 文件（.p7b）

步骤 4：在 DevEco Studio 中配置手动签名

步骤 4.1：File → Project Structure → Signing Configs

步骤 4.2：取消 "Automatically generate signature"

步骤 4.3：手动填写各项：
├── Store file: 选择 .p12 密钥库文件路径
├── Store password: 密钥库密码
├── Key alias: 密钥别名
├── Key password: 密钥密码
├── Certpath: 选择 .cer 证书文件路径
├── Profile: 选择 .p7b Profile 文件路径
└── SignAlg: SHA256withECDSA（默认）

步骤 4.4：点击 "Apply" → "OK"

签名配置在 build-profile.json5 中的体现：

// build-profile.json5 中的签名配置示例
{
"app": {
"signingConfigs": [
{
"name": "default",
"type": "HarmonyOS",
"material": {
// 证书文件路径
"certpath": "D:\\\\MyApp\\\\keystore\\\\release.cer",
// 密钥库文件路径
"storeFile": "D:\\\\MyApp\\\\keystore\\\\myapp_release.p12",
// 密钥库密码（建议通过环境变量注入，不要明文存储）
"storePassword": "$KEYSTORE_PASSWORD",
// 密钥别名
"keyAlias": "myapp_key",
// 密钥密码
"keyPassword": "$KEY_PASSWORD",
// Profile 文件路径
"profile": "D:\\\\MyApp\\\\keystore\\\\release.p7b",
// 签名算法
"signAlg": "SHA256withECDSA"
}
},
{
"name": "debug",
"type": "HarmonyOS",
"material": {
"certpath": "./entry/src/main/signing/debug/internal/auto_sign.cer",
"storeFile": "./entry/src/main/signing/debug/internal/auto_sign.p12",
"storePassword": "00000019…", // 加密后的密码
"keyAlias": "debugKey",
"keyPassword": "00000019…",
"profile": "./entry/src/main/signing/debug/internal/auto_sign.p7b",
"signAlg": "SHA256withECDSA"
}
}
],
"products": [
{
"name": "default",
"signingConfig": "default", // 引用上面的签名配置
"compileSdkVersion": "5.0.0(12)",
"compatibleSdkVersion": "5.0.0(12)"
}
]
}
}

9.4 构建 HAP/APP 包

HarmonyOS 应用的构建产物主要有以下类型：

通过 IDE 构建：

构建 HAP（调试包）：
菜单 → Build → Build Hap(s)/APP(s) → Build Hap(s)
产物路径：entry/build/default/outputs/default/entry-default-unsigned.hap

构建 APP（发布包）：
菜单 → Build → Build Hap(s)/APP(s) → Build APP(s)
产物路径：build/outputs/default/MyApp-default-signed.app

构建 Release 版本：
1. 在 Build Variant 面板中选择 "release" 模式
2. Build → Build Hap(s)/APP(s) → Build Hap(s)

通过 Hvigor 命令行构建（适用于 CI/CD 场景）：

# 清理构建缓存
./hvigorw clean

# 构建 Debug HAP 包
./hvigorw assembleHap –no-daemon

# 构建 Release HAP 包
./hvigorw assembleHap -p buildMode=release –no-daemon

# 构建 APP 包（多模块应用整体打包）
./hvigorw assembleApp –no-daemon

# 构建指定模块的 HAP
./hvigorw -p module=entry@default assembleHap –no-daemon

# 构建 Release APP 包并指定输出目录
./hvigorw assembleApp -p buildMode=release -p output=D:\\output –no-daemon

# 构建 HAR 库模块
./hvigorw -p module=common assembleHar –no-daemon

# 构建并运行单元测试
./hvigorw assembleHap runTest –no-daemon

# 查看构建详细日志
./hvigorw assembleHap –log-level=debug –no-daemon

Hvigor 构建脚本示例：

// 项目根目录/hvigorfile.ts
// 项目级构建脚本

import { appTasks } from '@ohos/hvigor-ohos-plugin';

export default {
system: appTasks, // 使用系统预设的应用构建任务集
plugins: [] // 可在此添加自定义构建插件
}

// entry/hvigorfile.ts
// 模块级构建脚本

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { hvigor, HvigorNode } from '@ohos/hvigor';

/**
* 自定义构建插件示例：
* 在构建前自动替换版本号
*/
function versionReplacePlugin(): any {
return {
pluginId: 'VersionReplacePlugin',
apply(node: HvigorNode) {
// 在 preBuild 阶段执行
node.registerTask({
name: 'replaceVersion',
run: (taskContext) => {
const fs = require('fs');
const configPath = `${node.nodeDir}/src/main/module.json5`;
if (fs.existsSync(configPath)) {
let content = fs.readFileSync(configPath, 'utf-8');
// 替换版本号
content = content.replace(
/"versionCode":\\s*\\d+/,
`"versionCode": ${Date.now()}`
);
fs.writeFileSync(configPath, content, 'utf-8');
console.log('版本号已自动更新');
}
}
});
}
}
}

export default {
system: hapTasks, // 使用系统预设的 HAP 构建任务集
plugins: [versionReplacePlugin()] // 注册自定义插件
}

9.5 发布到 AppGallery Connect

发布流程概览：

发布上架完整流程：

1. 准备阶段
├── 完成应用开发和测试
├── 准备应用图标和截图素材
├── 编写应用描述和更新说明
└── 准备隐私政策链接

2. 创建应用
├── 登录 AppGallery Connect
├── 创建项目（如未创建）
├── 添加 HarmonyOS 应用
└── 填写应用基本信息

3. 签名与打包
├── 申请发布证书
├── 申请发布 Profile
├── 配置手动签名
└── 构建 Release APP 包

4. 上传与审核
├── 上传 APP 包
├── 填写应用信息（名称、描述、截图等）
├── 设置定价和分发区域
├── 提交审核
└── 等待审核通过（通常 1-3 个工作日）

5. 发布
├── 审核通过后手动发布
└── 或设置定时发布

上传应用包：

步骤 1：登录 AppGallery Connect
https://developer.huawei.com/consumer/cn/service/josp/agc/index.html

步骤 2：进入 "我的项目" → 选择项目 → "版本信息"

步骤 3：点击 "新建版本" 或 "更新版本"

步骤 4：上传 APP 包
点击 "上传软件包" → 选择本地构建的 .app 文件
等待上传和自动检测完成

步骤 5：填写版本信息
├── 版本号
├── 新版本特性（更新说明）
├── 应用截图（至少 3 张）
├── 应用图标
└── 隐私政策链接

步骤 6：设置分发信息
├── 选择分发区域
├── 设置定价策略
└── 选择设备类型

步骤 7：提交审核
确认所有信息无误后点击 "提交审核"

重要提示：

• 发布包必须使用发布证书签名，不能使用调试证书
• 应用包名（Bundle Name）必须与 AppGallery Connect 中注册的一致
• 隐私政策是必选项，必须提供可访问的隐私政策链接
• 应用截图需符合华为应用市场的尺寸和质量要求

十、高级配置与优化

10.1 IDE 个性化设置

DevEco Studio 基于 IntelliJ IDEA，提供了丰富的个性化设置选项：

主题与外观：

File → Settings → Appearance & Behavior → Appearance

常用设置：
├── Theme: Darcula（暗色主题）/ Light（亮色主题）
├── UI Options:
│ ├── ☑ Use custom font 自定义 UI 字体
│ ├── Font size: 14 UI 字体大小
│ └── ☑ Show tree indent guides 显示树结构缩进线
└── Accessibility:
├── ☑ Enable mnemonics 启用键盘快捷键提示
└── ☑ Enable mnemonics for controls

编辑器设置：

File → Settings → Editor

关键设置项：
├── Font:
│ ├── Font: JetBrains Mono / Fira Code 等宽编程字体
│ ├── Size: 16 字体大小
│ ├── Line spacing: 1.2 行间距
│ └── ☑ Enable ligatures 启用连字符（=> ≠ 等）
│
├── Color Scheme:
│ └── 语法高亮配色方案（推荐 One Dark / Dracula）
│
├── Code Style → ArkTS:
│ ├── Tab size: 2 缩进空格数
│ ├── Indent: 2 缩进宽度
│ ├── Continuation indent: 4 续行缩进
│ └── ☑ Use tab character: false 使用空格而非 Tab
│
├── General:
│ ├── ☑ Show line numbers 显示行号
│ ├── ☑ Show method separators 显示方法分隔线
│ ├── ☑ Highlight current line 高亮当前行
│ ├── ☑ Show breadcrumb above editor 显示面包屑导航
│ └── Soft Wraps: On 自动换行
│
└── Code Folding:
├── ☑ Show code folding outline 显示折叠按钮
├── ☑ Collapse imports 默认折叠导入语句
└── ☑ Collapse file header 默认折叠文件头注释

快捷键自定义：

File → Settings → Keymap

常用自定义快捷键配置：
├── 搜索 "Run" → 设置运行快捷键为 F5
├── 搜索 "Debug" → 设置调试快捷键为 Shift+F5
├── 搜索 "Preview" → 设置预览快捷键为 Ctrl+P
├── 搜索 "Reformat Code" → 设置为 Ctrl+Alt+L
└── 支持导入 Eclipse / VS Code 快捷键方案

10.2 插件管理与扩展

DevEco Studio 支持安装 IntelliJ IDEA 兼容插件：

插件管理入口：

File → Settings → Plugins

三种插件来源：
├── Marketplace – JetBrains 插件市场（在线搜索安装）
├── Installed – 已安装插件管理
└── ⚙ → Install Plugin from Disk… – 从本地文件安装

推荐插件列表：

Hvigor 构建插件开发：

Hvigor 是 HarmonyOS 的构建工具，支持开发者编写自定义构建插件：

// hvigorfile.ts 中开发自定义 Hvigor 插件

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { HvigorNode, HvigorPlugin } from '@ohos/hvigor';

/**
* 自定义 Hvigor 插件：构建后自动复制产物到指定目录
*
* 功能说明：
* – 在 HAP 构建完成后，自动将 .hap 文件复制到部署目录
* – 支持根据构建模式（debug/release）分类存放
*/
export function autoCopyOutputPlugin(deployDir: string): HvigorPlugin {
return {
pluginId: 'AutoCopyOutputPlugin',
apply(node: HvigorNode) {
// 获取当前构建模式
const buildMode = node.getTaskParam('buildMode') || 'debug';

// 注册构建后任务
node.afterEvaluate(() => {
console.log(`[AutoCopy] 构建模式: ${buildMode}`);
console.log(`[AutoCopy] 部署目录: ${deployDir}`);
});

// 注册自定义任务
node.registerTask({
name: 'copyOutput',
// 依赖于 assembleHap 任务
dependencies: ['assembleHap'],
run: (taskContext) => {
const fs = require('fs');
const path = require('path');

// 构建输出目录
const outputDir = path.join(node.nodeDir, 'build', 'default', 'outputs', 'default');
// 目标目录
const targetDir = path.join(deployDir, buildMode);

// 创建目标目录
if (!fs.existsSync(targetDir)) {
fs.mkdirSync(targetDir, { recursive: true });
}

// 复制 HAP 文件
const files = fs.readdirSync(outputDir);
for (const file of files) {
if (file.endsWith('.hap')) {
const src = path.join(outputDir, file);
const dest = path.join(targetDir, file);
fs.copyFileSync(src, dest);
console.log(`[AutoCopy] 已复制: ${file} → ${targetDir}`);
}
}
}
});
}
};
}