1. 引言在鸿蒙OSHarmonyOS应用开发中配置文件是应用工程的“骨架”它决定了应用如何被系统识别、如何申请权限、如何声明页面与组件。无论是初学者还是有一定经验的开发者理解配置文件的结构与字段含义都是构建可发布、可维护应用的基础。本文将从配置文件的作用、核心文件结构、字段详解到实战示例系统梳理鸿蒙OS应用配置文件的完整知识体系。2. 配置文件概述鸿蒙OS应用工程中配置文件主要分为两类一类是应用级配置用于声明应用的全局信息如应用名称、版本号、图标等另一类是模块级配置用于描述某个模块Module的详细信息包括模块名称、入口页面、权限申请、设备类型等。两者配合共同构成应用在系统层面的完整描述。在 HarmonyOS 工程中最常见的配置文件包括app.json5应用级配置文件位于工程的 AppScope 目录下。module.json5模块级配置文件位于每个模块的 src/main 目录下。build-profile.json5构建配置文件用于声明签名、编译选项等。hvigorfile.ts构建脚本文件用于配置构建任务。其中app.json5和module.json5是开发者日常接触最多、也最需要深入理解的两个文件。3. app.json5 应用级配置详解app.json5位于工程的AppScope目录下用于声明应用级别的全局属性。它包含应用包名、版本号、图标、标签等关键信息是应用上架和安装时的重要依据。下面是一个典型的app.json5示例{ app: { bundleName: com.example.myapplication, vendor: example, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name } }各字段含义如下字段名类型说明bundleNamestring应用包名全局唯一用于标识应用。vendorstring应用供应商名称用于标识应用开发者。versionCodenumber应用版本号内部版本号用于版本管理必须为整数。versionNamestring应用版本名称用于向用户展示的版本号。iconstring应用图标资源引用通常使用资源索引。labelstring应用名称资源引用用于在桌面显示的应用名称。需要注意的是bundleName一旦发布后不可更改因此在创建工程时就要规划好包名。版本号versionCode在每次上架新版本时都需要递增否则会被应用市场拒绝。4. module.json5 模块级配置详解module.json5位于模块的src/main目录下是模块级配置的核心文件。它声明了模块的名称、类型、入口页面、权限、设备类型等信息。下面是一个典型的module.json5示例{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:icon, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ], requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:reason_internet, usedScene: { abilities: [ EntryAbility ], when: inuse } } ] } }下面对关键字段进行逐一说明。4.1 模块基本信息name字段表示模块名称在工程内必须唯一。type字段表示模块类型常见取值包括entry应用的主入口模块一个应用有且仅有一个。feature应用的动态特性模块可以按需加载。har静态共享库模块用于代码和资源复用。hsp动态共享库模块支持按需加载。mainElement字段指定模块的入口 Ability 名称即应用启动时首先加载的页面能力。deviceTypes数组声明了该模块支持的设备类型如手机、平板、智慧屏等。4.2 页面配置pages字段通过资源索引引用一个配置文件该文件列出了模块内所有的页面路径。例如$profile:main_pages对应src/main/resources/base/profile/main_pages.json文件其内容如下{ src: [ pages/Index, pages/Detail, pages/About ] }页面路径相对于src/main/ets目录不需要写文件扩展名。系统会根据该列表生成路由表用于页面跳转。4.3 Ability 配置abilities数组用于声明模块内的所有 Ability。每个 Ability 可以配置名称、入口文件、图标、标签、是否可被外部调用等属性。其中skills字段用于声明 Ability 能够响应的意图Intent例如上面的示例中声明了entity.system.home和action.system.home表示该 Ability 是应用的主入口会在桌面显示应用图标。4.4 权限申请requestPermissions数组用于声明模块运行时需要的权限。每个权限项包含权限名称、申请原因和使用场景。例如申请网络权限{ name: ohos.permission.INTERNET, reason: $string:reason_internet, usedScene: { abilities: [ EntryAbility ], when: inuse } }when字段取值包括inuse使用时申请和always始终可用。对于敏感权限系统会在应用运行时弹出授权对话框开发者需要在代码中通过abilityAccessCtrl模块主动发起授权请求。5. 资源文件与配置的关联在配置文件中很多字段的值并不是直接写死的字符串而是通过资源索引引用。例如$string:app_name表示引用字符串资源$media:app_icon表示引用图片资源$color:start_window_background表示引用颜色资源。这种设计的好处是支持多语言适配不同语言环境下自动加载对应的字符串资源。支持多设备适配不同设备类型可以加载不同的资源。便于统一管理和维护修改资源文件无需改动配置文件。字符串资源定义在src/main/resources/base/element/string.json文件中示例如下{ string: [ { name: app_name, value: 我的应用 }, { name: module_desc, value: 主模块 }, { name: reason_internet, value: 需要访问网络以获取数据 } ] }颜色资源定义在src/main/resources/base/element/color.json文件中{ color: [ { name: start_window_background, value: #FFFFFF } ] }6. 实战创建一个完整的配置文件下面通过一个完整的实战案例演示如何从零配置一个支持多页面、多权限的鸿蒙OS应用。假设我们要开发一个新闻阅读应用包含首页、详情页和设置页三个页面需要网络权限和位置权限。6.1 创建工程结构首先创建工程目录结构MyNewsApp/ ├── AppScope/ │ ├── app.json5 │ └── resources/ │ └── base/ │ ├── element/ │ │ └── string.json │ └── media/ │ └── app_icon.png └── entry/ └── src/ └── main/ ├── module.json5 ├── ets/ │ ├── entryability/ │ │ └── EntryAbility.ets │ └── pages/ │ ├── Index.ets │ ├── Detail.ets │ └── Settings.ets └── resources/ └── base/ ├── element/ │ ├── string.json │ └── color.json └── profile/ └── main_pages.json6.2 配置 app.json5{ app: { bundleName: com.example.mynewsapp, vendor: example, versionCode: 1000001, versionName: 1.0.1, icon: $media:app_icon, label: $string:app_name } }6.3 配置 module.json5{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:icon, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ], requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:reason_internet, usedScene: { abilities: [ EntryAbility ], when: always } }, { name: ohos.permission.LOCATION, reason: $string:reason_location, usedScene: { abilities: [ EntryAbility ], when: inuse } } ] } }6.4 配置页面列表在src/main/resources/base/profile/main_pages.json中声明页面{ src: [ pages/Index, pages/Detail, pages/Settings ] }6.5 配置字符串资源在src/main/resources/base/element/string.json中定义模块相关字符串{ string: [ { name: module_desc, value: 新闻阅读主模块 }, { name: EntryAbility_desc, value: 新闻阅读应用入口 }, { name: EntryAbility_label, value: 新闻阅读 }, { name: reason_internet, value: 需要访问网络以加载新闻内容 }, { name: reason_location, value: 需要获取位置以推荐本地新闻 } ] }6.6 配置颜色资源在src/main/resources/base/element/color.json中定义启动窗口背景色{ color: [ { name: start_window_background, value: #F5F5F5 } ] }7. 常见问题与注意事项在实际开发中配置文件相关的错误往往比较隐蔽下面总结几个常见问题。7.1 bundleName 冲突bundleName是应用的唯一标识如果与其他应用重复会导致安装失败。建议使用公司域名反写作为前缀例如com.example.myapp。7.2 页面路径错误main_pages.json中的页面路径必须与ets/pages目录下的文件一一对应且不能包含文件扩展名。如果路径错误编译时会报“页面不存在”的错误。7.3 权限声明不完整某些权限需要同时声明reason和usedScene否则在应用市场上架审核时会被驳回。特别是涉及用户隐私的权限如位置、相机、通讯录等必须提供清晰的使用场景说明。7.4 资源引用错误配置文件中使用$string:、$media:、$color:等前缀引用资源时必须确保对应的资源文件存在且名称正确。如果资源缺失编译时会报资源引用错误。8. 总结本文系统梳理了鸿蒙OS应用配置文件的核心内容包括app.json5和module.json5的结构、字段含义、资源关联方式并通过一个完整的新闻阅读应用案例演示了配置文件的编写过程。掌握配置文件是鸿蒙开发的第一步也是构建高质量应用的基础。建议开发者在实际项目中多参考官方文档并结合 DevEco Studio 的工程模板进行实践逐步加深对配置体系的理解。