构建鸿蒙5.0应用-项目结构篇（二）

最新推荐文章于 2025-04-24 15:35:43 发布

快进小树林

最新推荐文章于 2025-04-24 15:35:43 发布

阅读量1.3k

点赞数 15

分类专栏：鸿蒙Next 文章标签： harmonyos 华为

本文链接：https://blog.youkuaiyun.com/chenzhiyong12/article/details/144169248

版权

鸿蒙Next 专栏收录该内容

2 篇文章

订阅专栏

初始化一个鸿蒙应用后，项目目录下一般会初始化一些目录，理解鸿蒙项目的目录结构对于我们来说非常重要，因为它涉及到代码和资源文件的组织管理。

我们以这份代码为例，学习一下如何组织鸿蒙应用的工程目录：基于鸿蒙OS NEXT开发的高仿微信APP

项目结构说明

｜——.hvigor          鸿蒙应用工程中负责存储构建过程中的缓存和报告的地方
｜——.idea            包含了IDE的项目管理配置
｜——AppScope         存放应用级别的静态资源，如应用图标、应用名称等字符串、多媒体文件等
    ｜——app.json5    鸿蒙应用的全局配置文件，用于存放应用公共的配置信息。这个文件包含了应用的基本 
                     信息，如包名、版本、图标和名称等
｜——entry            HarmonyOS工程模块，存放主要应用代码，编译构建生成一个HAP包。
    ｜——.preview     存放预览器在运行时生成的临时文件
    ｜——src
        ｜——main
            ｜——ets
                ｜——component        应用组件存放位置
                ｜——entryability     存放应用的入口文件，是应用的启动点，定义了应用的入口能力（                                                                        
                                     Ability），它是应用生命周期管理的核心，类似微信小程序开发中 
                                     的app.js
                ｜——pages            应用页面的存放位置
                ｜——utils            工具类的存放位置
            ｜——resource             应用静态资源存放目录
            ｜——module.json5        模块配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上 
                                    的配置信息以及应用/服务的全局配置信息
        ｜——ohTest        单元测试、自动化测试等测试代码的存放位置
    ｜——.gitignore 
    ｜——build-profile.json5
    ｜——hvigorfile.ts 
    ｜——oh-package.json5 
｜——hvigor           hvigor文件夹包含了Hvigor构建工具的配置文件和业务逻辑实现脚本
    ｜——hvigor-config.json5        控制和自定义项目的构建过程，包括编译、打包等任务
｜——oh_modules       工程的依赖包存放目录，项目中引用到的第三方组件在打包后会被编译到应用包中
｜——.gitignore       设置工程需要忽略上传的目录或文件，例如oh_modules
｜——build-profile.json5     包含了整个工程的构建配置，如签名信息、编译SDK版本、兼容SDK版本、产品 
                            配置等。它定义了工程的签名配置、产品配置（如默认版、付费版、免费版 
                            等），以及模块信息和目标构建配置，告诉Hvigor如何构建你的应用或服务
｜——hvigorfile.ts           工程级编译构建任务脚本，允许开发者定义和配置项目的构建任务。这些任务    
                            可能包括编译、打包、混淆、测试等各个阶段
｜——oh-package.json5        工程级依赖配置文件，用于记录引入包的配置信息，类似vue工程的                
                            package.json
｜——oh-package-lock.json5   依赖包版本锁定文件
｜——README.md               工程的说明文件及项目备注一般写在这个文件内，以便开发人员阅读
｜——External Libraries      实际上并不属于工程目录，包含了构建应用过程中所需要的外部依赖，与                    
                            oh_modules不同，这里面的代码不会被编译到应用包中，只是为了构建应用提 
                            供支持

工程构建思想

整个工程的文件目录关系看起来应该是如下：

ohpm负责包资源管理，添加依赖到oh-package/oh-package-lock，依赖下载到oh_modules

oh_modules中的依赖为各业务模块提供依赖支持

hvigor把各应用模块打包成HAP应用，中间生成.hvigor缓存，方便下次打包使用

hvigorfile和build-profile为hvigor打包构建提供物料3及插件支持

hvigorw通过sync同步构建依赖到hvigor-config，为hvigorfile使用第三方依赖提供支持

`AppScope/app.json5`文件中的配置信息

完整配置可以参考app.json5应用配置

本项目中的配置包括：

bundleName：标识应用的包名，用于唯一标识应用。
vendor：标识应用的供应商或开发者。
versionCode：用于区分应用版本的数字，通常每次发布新版本时递增。
versionName：应用的版本号，通常以字符串形式表示，如"1.0.0"。
icon：对应于应用的显示图标，通常是一个资源引用。
label：应用的名称，用于在设备上显示给用户

module.json5完整配置

完整配置可参考module.json5配置说明

本项目中的配置包括：

{
  "module": {
    "name": "entry", //模块的名称，这里被设置为"entry"
    "type": "entry", //模块的类型，这里被设置为"entry"，表示这是一个入口模块，还支持feature｜har｜shared
    "description": "$string:module_desc", //模块的描述，引用resource/base/elemment/sring.json的module_desc的值
    "mainElement": "EntryAbility", //指定模块的主元素，这里被设置为"EntryAbility"
    "deviceTypes": [ //定义了模块支持的设备类型
      "phone",
      "tablet"
    ],
    "requestPermissions": [ //定义了模块需要请求的权限，这里请求了互联网权限"ohos.permission.INTERNET"，并提供了使用场景和理由
      {
        "name": "ohos.permission.INTERNET", //参考https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/permissions-for-all-V5
        "reason": "$string:net_permission_reason",
        "usedScene": { //权限使用的场景，该字段用于应用上架校验。包括abilities和when两个子项。

- abilities：使用权限的UIAbility或者ExtensionAbility组件的名称。

- when：调用时机。
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ],
    "deliveryWithInstall": true, //模块是否随安装包一起交付，这里被设置为true
    "installationFree": false, //表示模块是否支持免安装，这里被设置为false，表示需要安装
    "pages": "$profile:main_pages", //定义了模块包含的页面，引用resource/base/profile/main_pages.json
    "abilities": [ //定义了模块的能力（Ability），这里是"EntryAbility"
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets", //Ability的源代码入口文件路径
        "description": "$string:EntryAbility_desc", //Ability的描述
        "icon": "$media:wechat_logo", //Ability的图标
        "label": "$string:EntryAbility_label", //Ability的标签
        "startWindowIcon": "$media:icon", //启动窗口的图标
        "startWindowBackground": "$color:start_window_background", //启动窗口的背景色
        "exported": true, //表示Ability是否被导出，这里被设置为true，表示Ability可以被其他应用或服务访问
        "skills": [ //定义了Ability的技能集，这里包含了实体和动作，用于描述Ability的能力范围
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

oh-package-lock.json

鸿蒙应用似乎延续现有的工程架构思想，依赖包管理采用版本锁定文件，初学者可能不太理解为什么需要这个文件，觉得不是有oh-package.json做版本管理么？事实上oh-package中的依赖包采用“^1.11.7”这种形式，意味着如果依赖包有版本更新，将允许安装新版本依赖，这就可能造成A开发者本地安装的是v1.11.7，B开发者本地安装的是v1.11.8，如果新版本的依赖包出现bug，则两位开发人员的实现效果会不一致，甚至出现生产问题。

版本形式说明：参考深度解析package-lock.json作用

指定版本：比如 1.2.2 ，遵循“大版本.次要版本.小版本”的格式规定，安装时只安装指定版本。
波浪号（tilde）+指定版本：比如 ~1.2.2 ，表示安装 1.2.x 的最新版本（不低于1.2.2），但是不安装 1.3.x，也就是说安装时不改变大版本号和次要版本号。
插入号（caret）+指定版本：比如 ˆ1.2.2，表示安装 1.x.x 的最新版本（不低于 1.2.2），但是不安装 2.x.x，也就是说安装时不改变大版本号。需要注意的是，如果大版本号为 0，则插入号的行为与波浪号相同，这是因为此时处于开发阶段，即使是次要版本号变动，也可能带来程序的不兼容。
latest：安装最新版本。

理解hvigor配置文件职能

hvigor是鸿蒙应用和服务的构建工具，初学时看到工程里面有build-profile.json5、hvigorfile.ts、hvigor/hvigor-config.json5、.hvigor这些配置文件不甚了解，容易犯浑，官方对这些配置文件的定义如下图所示：

build-profile.json5：指导hvigor要构建什么应用/服务、产品，应用包含的模块信息、签名等
hvigor-config.json5：开发需要添加自定义插件依赖时，需要在此文件中声明依赖包及版本信息，声明依赖包后在hvigorfile.ts文件中才能引用，参官方hvigor-profile.json5配置文件说明
hvigorfile.ts：构建过程需要使用自定义插件依赖时，在此文件导入插件并使用
build-profile.json5：指导hvigor要构建什么应用，参考官方build-profile.json配置文件说明
.hvigor：存放构建过程中的缓存、报告等信息

打个比方，build-profile相当于总指挥，告诉团队要做什么，hvigor-config相记录了团队需要什么样的人才，hvigorfile调用这些人才把活干起来，.hvigor则保存团队干出来的成果，方便下次继续使用。

为什么entry目录和工程根目录各自配了一套.gitignore、hivigorfile、build-profile、oh-package？

很多朋友可能会纳闷为什么根目录配置了一套这些配置文件，entry目录又配置了一套，其实这是鸿蒙应用开发过程考虑多团队、管理多模块的大型复杂应用而设计的，例如支付宝有不同的应用模块包括支付、购物、出行等，不同的设备的入口也可能不一样，例如手机、可穿戴设备、平板、折叠屏等，因此需要支持不同功能模块的特定打包配置及依赖，初学者功力不够后续可以深入了解鸿蒙模块化设计