应用配置文件解读

应用配置文件

今天需要了解一下应用的配置文件，只有很好的了解配置文件，那么开发OpenHarmony应用开发其实也就很简单了。

先来了解一下目录结构

jianguo@nutpi Atomgit_X % tree -L 5
.
├── AppScope
│   ├── app.json5
│   └── resources
│       └── base
│           ├── element
│           │   └── string.json
│           └── media
│               └── app_icon.png
├── build-profile.json5
├── code-linter.json5
├── entry
│   ├── build-profile.json5
│   ├── hvigorfile.ts
│   ├── obfuscation-rules.txt
│   ├── oh-package.json5
│   └── src
│       ├── main
│       │   ├── ets
│       │   │   ├── entryability
│       │   │   └── pages
│       │   ├── module.json5
│       │   └── resources
│       │       ├── base
│       │       ├── en_US
│       │       ├── rawfile
│       │       └── zh_CN
│       ├── mock
│       │   └── mock-config.json5
│       ├── ohosTest
│       │   ├── ets
│       │   │   └── test
│       │   └── module.json5
│       └── test
│           ├── List.test.ets
│           └── LocalUnit.test.ets
├── hvigor
│   └── hvigor-config.json5
├── hvigorfile.ts
├── local.properties
├── oh-package-lock.json5
├── oh-package.json5
└── oh_modules
    └── @ohos
        ├── hamock -> ../.ohpm/@ohos+hamock@1.0.0/oh_modules/@ohos/hamock
        └── hypium -> ../.ohpm/@ohos+hypium@1.0.19/oh_modules/@ohos/hypium

27 directories, 19 files

工程结构主要包含的文件类型及用途如下：

说明：

• AppScope目录由DevEco Studio自动生成，不可更改。
• Module目录名称可以由DevEco Studio自动生成（比如entry、library等），也可以自定义。为了便于说明，下表中统一采用Module_name表示。

文件类型	说明
配置文件	包括应用级配置信息、以及Module级配置信息： - AppScope > app.json5：app.json5配置文件，用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。 - Module_name > src > main > module.json5：module.json5配置文件，用于声明Module基本信息、支持的设备类型、所含的组件信息、运行所需申请的权限等。
ArkTS源码文件	Module_name > src > main > ets：用于存放Module的ArkTS源码文件（.ets文件）。
资源文件	包括应用级资源文件、以及Module级资源文件，支持图形、多媒体、字符串、布局文件等，详见资源分类与访问。 - AppScope > resources ：用于存放应用需要用到的资源文件。 - Module_name > src > main > resources ：用于存放该Module需要用到的资源文件。
其他配置文件	用于编译构建，包括构建配置文件、编译构建任务脚本、混淆规则文件、依赖的共享包信息等。 - build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。 - hvigorfile.ts：应用级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。 - obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。 - oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。

代码结构了解了以后，我们就开始后面的内容。

每个应用项目的代码目录下必须包含应用配置文件，这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。

在基于Stage模型开发的应用项目代码下，都存在一个app.json5配置文件、以及一个或多个module.json5配置文件。

app.json5配置文件

表1 app.json5配置文件标签说明

属性名称	含义	数据类型	是否可缺省
bundleName	标识应用的Bundle名称，用于标识应用的唯一性。命名规则如下 ： - 由字母、数字、下划线和符号“.”组成，且必须以字母开头。 - 字符串最小长度为7字节，最大长度128字节。 - 推荐采用反域名形式命名（如“com.example.demo”，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。 对于随系统源码编译的应用，建议命名为“com.ohos.demo”形式，其中的ohos标识系统应用。	字符串	该标签不可缺省。
bundleType	标识应用的Bundle类型，用于区分应用或者原子化服务。支持的取值如下： - app：当前Bundle为应用。 - atomicService：当前Bundle为原子化服务。 - shared：当前Bundle为共享库应用，预留字段。 - appService：当前Bundle为系统级共享库应用，仅供系统应用使用。	字符串	该标签可缺省，缺省值为app。
debug	标识应用是否可调试。 - true：可调试，一般用于开发阶段。 - false：不可调试，一般用于发布阶段。	布尔值	由IDE编译构建时生成。该标签可缺省，缺省值为false。
icon	标识应用的图标，取值为图标资源文件的索引。	字符串	该标签不可缺省。
label	标识应用的名称，取值为字符串资源的索引，字符串长度不超过63字节。	字符串	该标签不可缺省。
description	标识应用的描述信息。取值为长度不超过255字节的字符串，内容为描述信息的字符串资源索引。	字符串	该标签可缺省，缺省值为空。
vendor	标识对应用开发厂商的描述，取值为长度不超过255字节的字符串。	字符串	该标签可缺省，缺省值为空。
versionCode	标识应用的版本号，取值为小于2^31次方的正整数。此数字仅用于确定某个版本是否比另一个版本更新，数值越大表示版本越高。 开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。	数值	该标签不可缺省。
versionName	标识向用户展示的应用版本号。 取值为长度不超过127字节的字符串，仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。 第一段：主版本号/Major，范围0~99，重大修改的版本，如实现新的大功能或重大变化。 第二段：次版本号/Minor，范围0~99，表示实现较突出的特点，如新功能添加或大问题修复。 第三段：特性版本号/Feature，范围0~99，标识规划的新版本特性。 第四段：修订版本号/Patch，范围0~999，表示维护版本，如修复bug。	字符串	该标签不可缺省。
minCompatibleVersionCode	标识应用能够兼容的最低历史版本号，用于应用跨设备兼容性判断。取值范围为0~2147483647。	数值	该标签可缺省，缺省值等于versionCode标签值。
minAPIVersion	标识应用运行需要的SDK的API最小版本。取值范围为0~2147483647。	数值	应用编译构建时由build-profile.json5中的compatibleSdkVersion自动生成。
targetAPIVersion	标识应用运行需要的API目标版本。取值范围为0~2147483647。	数值	应用编译构建时由build-profile.json5中的compileSdkVersion自动生成。
apiReleaseType	标识应用运行需要的API目标版本的类型，采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”，其中，N代表大于零的整数。 - Canary：受限发布的版本。 - Beta：公开发布的Beta版本。 - Release：公开发布的正式版本。	字符串	应用编译构建时根据当前使用的SDK的Stage自动生成。即便手动配置了取值，编译构建时也会被覆盖。
accessible	标识应用是否能访问应用的安装目录，仅针对Stage模型的系统应用和预置应用生效。	布尔值	该标签可缺省，缺省值为false。
multiProjects	标识当前工程是否支持多个工程的联合开发。 - true：当前工程支持多个工程的联合开发。多工程开发可参考多工程构建。 - false：当前工程不支持多个工程的联合开发。	布尔值	该标签可缺省，缺省值为false。
asanEnabled	标识应用程序是否开启asan检测，用于辅助定位buffer越界造成的crash问题。 - true：当前工程开启asan检测。 - false：当前工程不开启asan检测。	布尔值	该标签可缺省，缺省值为false。
tablet	标识对tablet设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion。 如果使用该属性对tablet设备做了特殊配置，则应用在tablet设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时tablet设备使用app.json5公共区域配置的属性值。
tv	标识对tv设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion。 如果使用该属性对tv设备做了特殊配置，则应用在tv设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时tv设备使用app.json5公共区域配置的属性值。
wearable	标识对wearable设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion。 如果使用该属性对wearable设备做了特殊配置，则应用在wearable设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时wearable设备使用app.json5公共区域配置的属性值。
car	标识对car设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion。 如果使用该属性对car设备做了特殊配置，则应用在car设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时car设备使用app.json5公共区域配置的属性值。
default	标识对default设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion。 如果使用该属性对default设备做了特殊配置，则应用在default设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时default设备使用app.json5公共区域配置的属性值。
targetBundleName	标识当前包所指定的目标应用, 标签值的取值规则和范围与bundleName标签一致。配置该字段的应用为具有overlay特征的应用。	字符串	该标签可缺省，缺省值为空。
targetPriority	标识当前应用的优先级，取值范围为1~100。配置targetBundleName字段之后，才支持配置该字段。	数值	该标签可缺省, 缺省值为1。
generateBuildHash	标识当前应用的所有HAP和HSP是否由打包工具生成哈希值。 该字段配置为true时，该应用下的所有HAP和HSP都会由打包工具生成对应的哈希值。系统OTA升级时，若应用的versionCode保持不变，可根据哈希值判断应用是否需要升级。 说明： 该字段仅对预置应用生效。	布尔值	该标签可缺省, 缺省值为false。
GWPAsanEnabled	标识应用程序是否开启GWP-asan堆内存检测工具，用于对内存越界、内存释放后使用等内存破坏问题进行分析。 - true：当前工程开启GWP-asan检测。 - false：当前工程不开启GWP-asan检测。	布尔值	该标签可缺省, 缺省值为false。
appEnvironments	标识当前模块配置的应用环境变量。	对象数组	该标签可缺省，缺省值为空。
maxChildProcess	标识当前应用自身可创建的子进程的最大个数，取值范围为0到512，0表示不限制，当应用有多个模块时，以entry模块的配置为准。	数值	该标签可缺省，缺省时使用系统配置的默认值。
multiAppMode	标识当前应用配置的多开模式。仅bundleType为app的应用的entry或feature模块配置有效，存在多个模块时，以entry模块的配置为准。	对象	该标签可缺省，缺省值为空。
hwasanEnabled	标识应用程序是否开启HWAsan检测。HWAsan(HardWare-assisted AddressSanitizer)是利用Top-Byte-Ignore特性实现的增强版Asan，与Asan相比HWAsan的内存开销更低，检测到的内存错误范围更大。 - true：当前工程开启HWAsan检测。 - false：当前工程不开启HWAsan检测。	布尔值	该标签可缺省，缺省值为false。
ubsanEnabled	标识应用程序是否开启UBsan检测。 UBsan(Undefined Behavior Sanitizer)是一个用于运行时检测程序中未定义行为的工具，旨在帮助开发人员发现代码中潜在的错误和漏洞。 - true：当前工程开启UBsan检测。 - false：当前工程不开启UBsan检测。	布尔值	该标签可缺省，缺省值为false。
cloudFileSyncEnabled	标识当前应用是否启用端云文件同步能力。 - true：当前应用启用端云文件同步能力。 - false：当前应用不启用端云文件同步能力。	布尔值	该标签可缺省，缺省值为false。
configuration	标识当前应用字体大小跟随系统配置的能力。 该标签是一个profile文件资源，用于指定描述应用字体大小跟随系统变更的配置文件。	字符串	该标签可缺省，缺省时configuration使用跟随系统默认设定。

module.json5 配置文件

module.json5配置文件包含以下标签。

表1 module.json5配置文件标签说明

属性名称	含义	数据类型	是否可缺省
name	标识当前Module的名称，确保该名称在整个应用中唯一。命名规则如下 ： - 由字母、数字和下划线组成，且必须以字母开头。 - 最大长度31字节。 应用升级时允许修改该名称，但需要应用适配Module相关数据目录的迁移，详见文件管理接口。	字符串	该标签不可缺省。
type	标识当前Module的类型。支持的取值如下： - entry：应用的主模块。 - feature：应用的动态特性模块。 - har：静态共享包模块。 - shared：动态共享包模块。	字符串	该标签不可缺省。
srcEntry	标识当前Module所对应的代码路径，取值为长度不超过127字节的字符串。	字符串	该标签可缺省，缺省值为空。
description	标识当前Module的描述信息，取值为长度不超过255字节的字符串，可以采用字符串资源索引格式。	字符串	该标签可缺省，缺省值为空。
process	标识当前Module的进程名，取值为长度不超过31字节的字符串。如果在HAP标签下配置了process，则该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。 说明： 仅支持系统应用配置，三方应用配置不生效。	字符串	该标签可缺省，缺省为app.json5文件下app标签下的bundleName。
mainElement	标识当前Module的入口UIAbility名称或者ExtensionAbility名称，取值为长度不超过255字节的字符串。	字符串	该标签可缺省，缺省值为空。
deviceTypes	标识当前Module可以运行在哪类设备上。	字符串数组	该标签不可缺省。
deliveryWithInstall	标识当前Module是否在用户主动安装的时候安装，即该Module对应的HAP是否跟随应用一起安装。 - true：主动安装时安装。 - false：主动安装时不安装。	布尔值	该标签不可缺省。
installationFree	标识当前Module是否支持免安装特性。 - true：表示支持免安装特性，且符合免安装约束。 - false：表示不支持免安装特性。 说明： 当bundleType为原子化服务时，该字段需要配置为true。反之，该字段需要配置为false。	布尔值	该标签不可缺省。
virtualMachine	标识当前Module运行的目标虚拟机类型，供云端分发使用，如应用市场和分发中心。如果目标虚拟机类型为ArkTS引擎，则其值为“ark+版本号”。	字符串	该标签由IDE构建HAP的时候自动插入。
pages	标识当前Module的profile资源，用于列举每个页面信息，取值为长度不超过255字节的字符串。	字符串	在有UIAbility的场景下，该标签不可缺省。
metadata	标识当前Module的自定义元信息，可通过资源引用的方式配置distributionFilter、shortcuts等信息。只对当前Module、UIAbility、ExtensionAbility生效。	对象数组	该标签可缺省，缺省值为空。
abilities	标识当前Module中UIAbility的配置信息，只对当前UIAbility生效。	对象数组	该标签可缺省，缺省值为空。
extensionAbilities	标识当前Module中ExtensionAbility的配置信息，只对当前ExtensionAbility生效。	对象数组	该标签可缺省，缺省值为空。
definePermissions	标识系统资源hap定义的权限，不支持应用自定义权限。	对象数组	该标签可缺省，缺省值为空。
requestPermissions	标识当前应用运行时需向系统申请的权限集合。	对象数组	该标签可缺省，缺省值为空。
testRunner	标识用于测试当前Module的测试框架的配置。	对象	该标签可缺省，缺省值为空。
atomicService	标识当前应用是原子化服务时，有关原子化服务的相关配置。	对象	该标签可缺省，缺省值为空。
dependencies	标识当前模块运行时依赖的共享库列表。	对象数组	该标签可缺省，缺省值为空。
targetModuleName	标识当前包所指定的目标module，确保该名称在整个应用中唯一。取值为长度不超过31字节的字符串，不支持中文。配置该字段的Module具有overlay特性。仅在动态共享包（HSP）中适用。	字符串	该标签可缺省，缺省值为空。
targetPriority	标识当前Module的优先级，取值范围为1~100。配置targetModuleName字段之后，才需要配置该字段。仅在动态共享包（HSP）中适用。	整型数值	该标签可缺省，缺省值为1。
proxyData	标识当前Module提供的数据代理列表。	对象数组	该标签可缺省，缺省值为空。
isolationMode	标识当前Module的多进程配置项。支持的取值如下： - nonisolationFirst：优先在非独立进程中运行。 - isolationFirst：优先在独立进程中运行。 - isolationOnly：只在独立进程中运行。 - nonisolationOnly：只在非独立进程中运行。	字符串	该标签可缺省，缺省值为nonisolationFirst。
generateBuildHash	标识当前HAP/HSP是否由打包工具生成哈希值。当配置为true时，如果系统OTA升级时应用versionCode保持不变，可根据哈希值判断应用是否需要升级。 该字段仅在app.json5文件中的generateBuildHash字段为false时使能。 说明： 该字段仅对预置应用生效。	布尔值	该标签可缺省，缺省值为false。
compressNativeLibs	在打包hap时，该字段标识libs库是否以压缩存储的方式打包到HAP。 - true：libs库以压缩方式存储。 - false：libs库以不压缩方式存储。 在应用安装时，该字段用于标识libs库是否需要解压出来（API14及之后版本支持，之前的版本均默认解压libs库）。 - true：libs库会解压出来。 - false：libs库不会解压出来。	布尔值	该标签可缺省，在打包hap时缺省值为false。在安装应用时，该字段未配置时默认为true。
libIsolation	用于区分同应用不同HAP下的.so文件，以防止.so冲突。 - true：当前HAP的.so文件会储存在libs目录中以Module名命名的路径下。 - false：当前HAP的.so文件会直接储存在libs目录中。	布尔值	该标签可缺省，缺省值为false。
fileContextMenu	标识当前HAP的右键菜单配置项。取值为长度不超过255字节的字符串。	字符串	该标签可缺省，缺省值为空。
querySchemes	标识允许当前应用进行跳转查询的URL schemes，只允许entry类型模块配置，最多50个，每个字符串取值不超过128字节。	字符串数组	该标签可缺省，缺省值为空。
routerMap	标识当前模块配置的路由表路径。取值为长度不超过255字节的字符串。	字符串	该标签可缺省，缺省值为空。
appEnvironments	标识当前模块配置的应用环境变量，只允许entry和feature模块配置。	对象数组	该标签可缺省，缺省值为空。
appStartup	标识当前Module启动框架配置路径，仅在Entry中生效。	字符串	该标签可缺省，缺省值为空。
hnpPackages	标识当前应用包含的Native软件包信息。只允许entry类型模块配置。

参考

app.json5配置文件

module.json5配置文件

备注

作者：夏天

链接：https://www.nutpi.net/

出处：https://www.arkui.club/

来源：坚果派

著作权归作者所有，禁止任何未经授权的个人或组织以任何形式将本案例集及其附属资料、创新、创意、架构设计、算法、衍生作品等用于任何商业目的、盈利活动、各类竞赛(比赛)、直播教学、录播教学、线下课程、书籍编写、教材编写、会议、培训、公益活动、项目课题、毕业设计、毕业论文、学术论文等。商业转载请联系作者获得授权，非商业转载请注明出处。否则追究相关责任。