鸿蒙应用项目目录结构详解

tsqtsqtsq0309

83人浏览 · 2026-08-22 23:21:37

tsqtsqtsq0309 · 2026-08-22 23:21:37 发布

在鸿蒙（HarmonyOS）应用开发中，清晰的项目目录结构是高效开发与维护的基础。基于 Stage 模型，一个鸿蒙应用工程项目通常采用模块化（Module）的设计思想，将不同功能或设备适配封装在不同的模块中。本文将深入剖析鸿蒙应用的标准目录结构，逐一讲解各个目录与文件的作用，帮助开发者建立起对项目全貌的系统性认知。

一、顶层工程结构概览

当您在 DevEco Studio 中创建一个鸿蒙应用工程时，默认会生成一个工程级目录，其下包含一个或多个模块级（Module）目录，以及若干工程级配置文件。

一个典型的工程根目录结构如下：

ProjectRoot/
├── AppScope/                 # 应用级全局资源与配置
├── entry/                    # 主模块（示例）
├── build-profile.json5       # 工程级编译配置
├── hvigorfile.ts             # 工程级编译构建脚本
├── oh-package.json5          # 工程级三方包依赖与配置
└── oh_modules/               # 工程级依赖存放目录

核心设计理念：模块化与多设备适配

鸿蒙采用多 Module 设计机制，每个 Module 均可独立编译，拥有自己的代码、资源和配置文件。这种设计带来了两大核心价值：

模块化开发：将不同功能（如支付模块、社交模块）封装为独立 Module，便于团队协作与代码复用。
多设备适配：每个 Module 可通过 deviceTypes 标签声明支持的设备类型（如手机、平板、车机），应用市场在分发时会根据设备类型精准匹配，实现按需组合部署。

工程级的 build-profile.json5 和 hvigorfile.ts 负责全局编译配置，而 oh-package.json5 则管理全局依赖。接下来，我们将逐一深入分析每个部分。

二、AppScope 目录：应用的“身份证”与全局资产

AppScope 目录是 DevEco Studio 自动生成的，用于存放应用级别的全局配置与资源。该目录名称不可更改，否则会导致编译失败。

其典型结构如下：

AppScope/
├── app.json5               # 应用的全局配置文件
└── resources/              # 应用级的公共资源文件
    ├── base/
    │   ├── element/        # 字符串、颜色、尺寸等基础资源
    │   ├── media/          # 图片、音频等多媒体资源
    │   └── profile/        # 其他配置文件（如自定义配置）
    └── en_US/              # 国际化资源（可选）

app.json5：应用的全局配置

app.json5 是应用级配置文件，不可或缺。它向编译工具、操作系统和应用市场提供应用的基本信息，主要包括：

bundleName：应用的唯一标识（如 com.example.myapp），采用反向域名规则命名。
vendor：开发厂商名称。
versionCode 与 versionName：版本号与展示版本名。
icon 与 label：应用图标与名称（支持资源索引）。
minAPIVersion 与 targetAPIVersion：兼容的最低 API 版本与目标 API 版本。
debug：调试模式开关（开发阶段为 true，发布时为 false）。
deviceTypes 特殊配置：支持为不同设备类型（如 tablet、car）单独指定 minAPIVersion 等属性，实现精细化的设备适配。

此外，从 API 26 开始，还支持 alternateIcons 标签，允许应用在运行时动态切换图标（如节日主题），极大提升了用户体验的灵活性。

理解要点：app.json5 配置的是整个应用的“身份信息”，它独立于具体模块，是应用在系统中注册和识别的依据。

三、Module 目录：功能单元的核心载体

每个 Module 都是一个功能独立的单元，可以编译为 HAP（Harmony Ability Package）、HAR（静态共享包）或 HSP（动态共享包）。最常见的 Module 类型为 entry（主模块），下面以 entry 为例展开讲解。

entry 模块典型结构

entry/
├── src/
│   └── main/
│       ├── ets/                 # ArkTS 源码目录
│       │   ├── entryability/    # UIAbility 入口（核心）
│       │   ├── entrybackupability/ # 备份恢复扩展能力
│       │   └── pages/           # 页面文件
│       ├── resources/           # 模块级资源文件
│       └── module.json5         # 模块配置文件
├── build-profile.json5          # 模块级编译配置
├── hvigorfile.ts                # 模块级构建脚本
├── obfuscation-rules.txt        # 代码混淆规则
├── oh-package.json5             # 模块级依赖管理
└── oh_modules/                  # 模块级三方依赖

3.1 src/main/ets：ArkTS 源码的“心脏”

ets 目录存放所有的 ArkTS 源代码，它是应用逻辑的实现地。

entryability/：这是应用/服务的入口 UIAbility 组件所在目录。UIAbility 是鸿蒙中具备 UI 界面的 Ability 类型，类似于 Android 的 Activity。一个应用可以有多个 Ability，但 entry 模块的入口 Ability 是应用启动时最先被拉起的组件。其源码文件通常为 EntryAbility.ets，负责处理应用生命周期（onCreate、onForeground、onBackground 等）和窗口初始化。
entrybackupability/：提供应用扩展的备份恢复能力。当应用需要支持数据备份与恢复时，可以通过该目录下的 EntryBackupAbility.ets 文件实现相关逻辑，让系统在特定场景下触发备份或恢复操作。
pages/：存放应用的页面文件（每个页面通常是一个 @Entry 装饰的组件）。页面是 UIAbility 内部的具体界面，通过路由进行切换。鸿蒙推荐“一个 UIAbility + 多个页面”的模式，以减少不必要的资源开销。页面文件一般以 .ets 为后缀，使用 ArkTS 声明式语法构建 UI。

3.2 src/main/resources：资源文件的“弹药库”

resources 目录用于存放模块所需的各类资源文件，包括：

图形资源（base/media/）：如 PNG、JPG、SVG 图片，以及分层图标（前景+背景）。
字符串资源（base/element/string.json）：支持多语言国际化，通过 $r('app.string.xxx') 引用。
颜色与尺寸（base/element/color.json 和 float.json）：定义主题色、间距、字体大小等。
布局与配置（base/profile/）：存放如 main_pages.json（页面路由配置）、form_config.json（卡片配置）等。

资源覆盖优先级：当 AppScope/resources 与模块级 resources 存在同名文件时，编译打包后 AppScope 的资源会覆盖模块级资源。这一机制允许开发者在应用层面统一替换某些资源，同时保持模块的独立性。

3.3 module.json5：模块的“说明书”

module.json5 是模块级配置文件，它定义了模块自身的属性、组件信息和权限要求。主要包括：

模块基本信息：name、type（entry/feature/har/shared）、description、deviceTypes（支持的设备列表）。
入口组件：mainElement 指定入口 UIAbility 的名称。
UIAbility 与 ExtensionAbility：在 abilities 和 extensionAbilities 数组中详细描述各组件的名称、启动模式（launchType）、图标、标签、是否可导出（exported）、支持的 Want 特征（skills）等。
权限声明：requestPermissions 数组列出应用运行所需申请的权限，并可通过 usedScene 指定使用场景与时机。
页面路由：pages 标签指向 profile 资源文件（如 $profile:main_pages），其中配置了页面路径与名称。
元数据（metadata）：可携带自定义配置，如快捷方式（shortcuts）、分发过滤策略（distributionFilter）等。

注意：在编译打包后，app.json5 中的全局字段会合并到 module.json5 中，生成最终的 module.json 文件，供系统运行时读取。

四、模块级其他关键文件

4.1 build-profile.json5（模块级）

该文件用于模块的编译构建配置，典型内容如下：

apiType：声明 Stage 模型。
buildOption：配置构建选项，如是否启用混淆（arkOptions.obfuscation）。
targets：定义不同的构建目标（如 release、debug），可为不同目标设置独立的配置。

开发者可在该文件中配置模块的签名信息、资源压缩选项（compressNativeLibs）等。

4.2 hvigorfile.ts（模块级）

hvigorfile.ts 是模块级的编译构建任务脚本。它基于 hvigor 构建工具链，开发者可在此自定义构建流程、修改构建参数或插入额外任务。默认情况下，该文件由 DevEco Studio 自动生成，一般无需手动修改。

4.3 obfuscation-rules.txt

该文件是代码混淆规则文件。当在 build-profile.json5 中开启混淆（enable: true），并在 Release 模式下编译时，构建工具会根据此文件中的规则对代码进行混淆、压缩和优化，有效保护代码资产，防止反编译。

混淆规则包括保留特定类名、方法名、属性名等，开发者可按需配置。

4.4 oh-package.json5（模块级）

此文件用于描述模块的包信息与依赖关系，类似 npm 的 package.json。主要包括：

name：模块名称。
version：模块版本。
dependencies：依赖的三方库或共享包（HAR/HSP），可指定本地路径（file:../library）或远程仓库版本。
main：入口声明文件（如 Index.ets），用于对外导出接口。

在构建时，构建工具会根据该文件解析并下载依赖。

4.5 oh_modules（模块级）

oh_modules 目录用于存放模块所依赖的三方库和共享包。该目录由构建工具自动生成和管理，开发者无需手动干预。当执行依赖安装命令时，所需的 HAR/HSP 会被下载至此目录。

五、工程级配置文件：全局统筹的“大脑”

5.1 build-profile.json5（工程级）

工程级 build-profile.json5 负责全局编译配置，比模块级配置优先级更高。主要内容包括：

signingConfigs：配置应用签名信息（如密钥库路径、密码、别名），用于调试或发布打包。
products：定义不同的产品形态，每个产品可指定不同的 bundleName、版本号、运行环境（HarmonyOS/OpenHarmony）等。默认情况下，产品名为 default。
modules：列出工程中包含的所有模块，并可对每个模块指定特定的构建参数。

通过 products 配置，开发者可在一套代码中构建出针对不同渠道或环境的多个应用变体。