本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、概述

Stage模型是HarmonyOS应用开发的核心架构，应用程序包在不同阶段呈现不同的形态结构。了解这些结构对于开发、构建和发布HarmonyOS应用至关重要。包含开发态、编译态和发布态的应用程序包结构。

二、开发态包结构

2.1 项目工程整体结构

在DevEco Studio中创建的项目工程通常包含以下主要目录和文件：

MyApplication/
├── AppScope/                    # 应用级目录（不可重命名）
├── entry/                      # 入口模块目录
├── feature/                    # 功能模块目录  
├── library/                    # 库模块目录
├── build-profile.json5         # 工程级构建配置
└── hvigorfile.ts               # 工程级构建脚本

2.2 关键目录

2.2.1 AppScope目录

• 重要性：由DevEco Studio自动生成，目录名称不可修改
• 包含内容：
  • app.json5 - 应用级配置文件
  • resources/ - 应用级资源文件
• 作用：存放整个应用共享的配置和资源

2.2.2 Module目录

• 命名规则：可由DevEco Studio自动生成或自定义
• 常见模块类型：
  • entry - 主入口模块
  • feature - 功能模块
  • library - 库模块
• 目录结构：

  ModuleName/
  ├── src/
  │   ├── main/
  │   │   ├── ets/              # ArkTS源码目录
  │   │   ├── resources/        # 模块资源目录
  │   │   └── module.json5      # 模块配置文件
  ├── build-profile.json5       # 模块级构建配置
  └── hvigorfile.ts            # 模块级构建脚本

2.3 配置文件详解

2.3.1 应用级配置（app.json5）

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

2.3.2 模块级配置（module.json5）

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "deviceTypes": ["default", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/mainability/MainAbility.ets",
        "description": "$string:mainability_desc",
        "icon": "$media:icon",
        "label": "$string:mainability_label",
        "exported": true
      }
    ]
  }
}

2.4 资源文件管理

2.4.1 资源目录结构

resources/
├── base/
│   ├── element/               # 字符串、颜色等资源
│   ├── media/                # 图片、音频等媒体资源
│   └── profile/              # 页面配置等资源
├── en_US/                    # 英文资源
└── zh_CN/                    # 中文资源

2.4.2 资源类型说明

• 图形资源：图标、图片等
• 多媒体资源：音频、视频文件
• 字符串资源：多语言文本
• 布局资源：页面布局配置
• 原始资源：直接使用的文件

2.5 其他重要文件

2.5.1 构建配置文件

• build-profile.json5 - 构建配置，包括签名、产品配置等
• hvigorfile.ts - 构建任务脚本，控制构建行为

2.5.2 代码质量文件

• obfuscation-rules.txt - 代码混淆规则文件
• oh-package.json5 - 依赖库信息配置
• code-linter.json5 - 代码检查规则配置

三、编译态包结构

3.1 模块类型与输出产物

3.1.1 模块类型对照表

模块类型	编译产物	说明
Entry模块	HAP	可独立运行的模块
Feature模块	HAP	功能模块，可独立分发
Library模块	HAR	静态共享包
	HSP	静态共享包

3.1.2 开发态与编译态视图对照

开发态视图：
MyApplication/
├── entry/src/main/ets/MainAbility.ets

编译态视图：
MyApplication/
├── entry/build/default/outputs/default/entry-default-unsigned.hap

3.2 HAP文件结构

entry-default-unsigned.hap
├── AbilityName.pkg
├── config.json
├── module.json
├── resources.index
└── assets/
    └── module.name/
        ├── ets/modules.abc
        └── resources/...

3.3 HAR文件结构

library.har
├── index.ets
├── *.so
├── resources/
└── oh-package.json5

四、发布态包结构

4.1 应用发布包（App Pack）

MyApplication_Release.app
├── entry.hap
├── feature1.hap
├── feature2.hap
└—— pack.info

4.2 多HAP机制

• 基础HAP：包含应用核心功能
• 功能HAP：按需下载的独立功能模块
• 资源HAP：分离的资源包，支持按需加载

4.3 分发模式

• 整包分发：所有HAP打包成一个App Pack
• 按需分发：基础HAP先安装，其他HAP按需下载

五、配置文件

5.1 app.json5完整配置示例

{
  "app": {
    "bundleName": "com.company.project",
    "vendor": "company",
    "versionCode": 1000001,
    "versionName": "1.0.1",
    "minAPIVersion": 10,
    "targetAPIVersion": 12,
    "apiReleaseType": "Release",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "description": "$string:app_desc",
    "distributionFilter": {
      "preinstall": "allow"
    }
  }
}

5.2 module.json5完整配置示例

{
  "module": {
    "name": "userprofile",
    "type": "feature",
    "description": "$string:userprofile_desc",
    "deviceTypes": ["phone", "tablet", "tv"],
    "deliveryWithInstall": false,
    "installationFree": true,
    "pages": "$profile:user_pages",
    "abilities": [
      {
        "name": "UserProfileAbility",
        "srcEntry": "./ets/userprofileability/UserProfileAbility.ets",
        "description": "$string:userprofile_ability_desc",
        "icon": "$media:profile_icon",
        "label": "$string:userprofile_ability_label",
        "startWindowIcon": "$media:start_icon",
        "startWindowBackground": "$color:start_bg",
        "exported": true,
        "skills": [
          {
            "actions": ["action.view.profile"],
            "entities": ["entity.user"],
            "uris": [
              {
                "scheme": "profile",
                "host": "user",
                "port": 8080,
                "path": "profile"
              }
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_USER_STORAGE",
        "reason": "$string:read_storage_reason",
        "usedScene": {
          "ability": ["UserProfileAbility"],
          "when": "always"
        }
      }
    ]
  }
}

六、建议

6.1 目录结构规划

1. 模块化设计：合理划分entry、feature、library模块
2. 资源管理：按类型和语言组织资源文件
3. 配置分离：不同环境使用不同的构建配置

6.2 配置优化

1. 权限申请：按需申请权限，明确使用场景
2. 设备适配：准确设置支持的设备类型
3. 版本管理：规范版本号和API版本控制

6.3 构建优化

1. 混淆配置：合理设置代码混淆规则
2. 依赖管理：使用oh-package.json5管理三方库
3. 多环境构建：配置不同的构建变体
4. 模块独立：每个模块可独立开发、编译和分发