鸿蒙基础之 JSON5 配置文件详解

m0_69682018

346人浏览 · 2026-05-07 10:21:40

m0_69682018 · 2026-05-07 10:21:40 发布

一、应用级配置

1. AppScope/app.json5

路径

AppScope/app.json5

定义

应用全局配置文件（应用身份证）

用于定义：

应用唯一标识
应用名称
应用图标
版本信息
API兼容信息
隐私配置

完整配置模板

{
  "app": {
    // 应用唯一包名（全局唯一）
    "bundleName": "com.example.harmonydemo",

    // 应用开发商名称
    "vendor": "example",

    // 应用版本号（整数，用于版本升级判断）
    "versionCode": 1000000,

    // 应用版本名称（展示给用户）
    "versionName": "1.0.0",

    // 构建版本号
    "buildVersion": "1",

    // 应用图标
    "icon": "$media:app_icon",

    // 应用名称
    "label": "$string:app_name",

    // 应用描述
    "description": "$string:app_description",

    // 最低兼容API版本
    "minAPIVersion": 10,

    // 目标API版本
    "targetAPIVersion": 12,

    // API兼容模式
    "apiCompatibilityMode": false,

    // 是否为调试模式
    "debug": false,

    // 隐私清单配置文件
    "privacyConfiguration": "$profile:privacy_config"
  }
}

重点

bundleName

真正的应用唯一标识（上架核心字段）

2. AppScope/pac.json5

路径

AppScope/pac.json5

定义

应用隐私清单文件

用于声明：

收集的数据
数据用途
是否追踪用户
是否与用户关联

完整配置模板

{
  "dataProcess": [
    {
      // 数据类型
      "dataType": "Location information",

      "dataLabels": [
        {
          // 数据标签
          "label": "GPS location",

          // 使用目的
          "purposes": [
            "App functionality"
          ],

          // 是否与用户身份关联
          "userLinked": true,

          // 是否用于跨应用跟踪
          "tracking": false
        }
      ]
    }
  ]
}

二、工程级配置

1. build-profile.json5

路径

工程根目录/build-profile.json5

定义

工程全局级构建配置文件

用于控制：

编译SDK
签名
应用产物
模块注册
全局构建规则

完整配置模板

{
  // 应用全局配置
  "app": {

    // 应用Bundle类型
    "bundleType": "app",

    // 是否为调试模式
    "debug": false,

    // 应用版本号
    "versionCode": 1000000,

    // 应用版本名称
    "versionName": "1.0.0",

    // 最低兼容版本号
    "minCompatibleVersionCode": 1000000,

    // 签名配置组
    "signingConfigs": [
      {
        // 签名方案名称（自定义唯一）
        "name": "default",

        // 固定值：HarmonyOS
        "type": "HarmonyOS",

        // 签名材料
        "material": {

          // p12证书文件
          "storeFile": "signature/xxx.p12",

          // p12密码
          "storePassword": "123456",

          // 密钥别名
          "keyAlias": "debugkey",

          // 密钥密码
          "keyPassword": "123456",

          // cer证书
          "certpath": "signature/xxx.cer",

          // profile文件
          "profile": "signature/xxx.p7b",

          // 签名算法
          "signAlg": "SHA256withECDSA"
        }
      }
    ],

    // 编译SDK版本
    "compileSdkVersion": 12,

    // 最低兼容SDK版本
    "compatibleSdkVersion": 10,

    // 产品配置
    "products": [
      {
        // 产品名称
        "name": "default",

        // 关联签名配置
        "signingConfig": "default",

        // 应用包名
        "bundleName": "com.example.harmonydemo",

        // 构建额外配置
        "buildOption": {

          // 是否允许调试
          "debuggable": true,

          // 是否开启源码检查
          "enableSourceCodeCheck": true,

          // 是否去重HAR依赖
          "deduplicateHar": true
        }
      }
    ]
  },

  // 项目模块注册
  "modules": [
    {
      // 模块名称
      "name": "entry",

      // 模块路径
      "srcPath": "./entry",

      // 关联产品
      "targets": [
        "default"
      ]
    }
  ],

  // 全局能力配置
  "capabilities": {},

  // 全局构建配置
  "buildOption": {},

  // 资源压缩配置
  "resOptions": {
    "compression": {
      "media": {
        "enable": true
      }
    }
  }
}

2. code-linter.json5

定义

全局代码规范检查配置

用于：

ArkTS代码检查
TypeScript规范检查
代码风格统一
性能/安全规则限制

完整配置模板

{
  // 需要检查的文件
  "files": [
    "**/*.ets",
    "**/*.ts"
  ],

  // 忽略目录
  "ignore": [
    "**/build/**/*",
    "**/oh_modules/**/*",
    "**/src/ohosTest/**/*"
  ],

  // 启用规则集
  "ruleSet": [
    "plugin:@typescript-eslint/recommended",
    "plugin:@hw-stylistic/recommended",
    "plugin:@security/recommended",
    "plugin:@performance/recommended"
  ],

  // 自定义规则
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "no-unused-vars": "warn"
  }
}

3. oh-package.json5

定义

OHPM 工程级依赖配置文件

类似：

package.json

完整配置模板

{
  // OHPM模型版本
  "modelVersion": "5.1.0",

  // 工程描述
  "description": "HarmonyOS工程OHPM配置",

  // 强制依赖覆盖（优先级最高）
  "overrides": {
    "@ohos/utils": "1.2.0"
  },

  // 依赖映射
  "overrideDependencyMap": {},

  // 参数文件
  "parameterFile": "./parameterFile.json5",

  // 自定义脚本
  "scripts": {
    "build": "hvigor build",
    "clean": "hvigor clean"
  },

  // 开发依赖
  "devDependencies": {
    "@ohos/hvigor": "2.2.1"
  }
}

4. oh-package-lock.json5

定义

OHPM自动生成的依赖锁文件

特点

自动生成
禁止手改
必须提交Git
锁定精确版本

结构示例

{
  "name": "工程名",

  "version": "1.0.0",

  "dependencies": {
    "@ohos/xxx": {

      "version": "x.x.x",

      "resolved": "仓库地址",

      "integrity": "哈希校验值",

      "dependencies": {}
    }
  }
}

5. hvigor-config.json5

定义

Hvigor构建工具配置

用于：

并行编译
增量编译
日志控制
内存控制

完整配置模板

{
  // Hvigor模型版本
  "modelVersion": "6.1.0",

  "dependencies": {
    "@ohos/hvigor-ohos-plugin": "2.2.1"
  },

  "execution": {

    // 构建分析模式
    "analyze": "normal",

    // 守护进程
    "daemon": true,

    // 增量编译
    "incremental": true,

    // 并行编译
    "parallel": true,

    // 类型检查
    "typeCheck": false
  },

  "logging": {

    // 日志级别
    "level": "info"
  },

  "nodeOptions": {

    // Node最大内存
    "maxOldSpaceSize": 8192
  }
}

6. hvigorfile.ts

定义

构建脚本文件

类似 Android 的：

build.gradle

工程级示例

import { appTasks } from '@ohos/hvigor-ohos-plugin';

export default {
  system: appTasks,
  plugins: []
}

三、模块级配置

9. entry/build-profile.json5

定义

模块级构建配置

优先级：

模块级 > 工程级

完整配置模板

{
  // Stage模型固定值
  "apiType": "stageMode",

  // 是否展示在服务中心
  "showInServiceCenter": true,

  // 模块构建配置
  "buildOption": {

    // Native配置
    "externalNativeOptions": {

      // CMake路径
      "path": "./src/main/cpp/CMakeLists.txt",

      "arguments": "",

      // 支持ABI
      "abiFilters": [
        "armeabi-v7a",
        "arm64-v8a"
      ]
    },

    // ArkTS配置
    "arkOptions": {

      // 混淆配置
      "obfuscation": {

        // 混淆规则文件
        "ruleFiles": [
          "./obfuscation-rules.txt"
        ],

        // 是否开启混淆
        "enable": true
      }
    }
  }
}

10. entry/oh-package.json5

定义

模块级依赖配置文件

用于：

模块包信息声明
模块依赖管理
模块入口定义
动态依赖配置

完整配置模板

{
  // 模块唯一名称
  "name": "@demo/entry",

  // 模块版本号
  "version": "1.0.0",

  // 项目主页
  "homepage": "https://gitee.com/demo/entry",

  // 仓库地址
  "repository": "https://gitee.com/demo/entry.git",

  // 搜索关键词
  "keywords": [
    "entry",
    "main"
  ],

  // 兼容SDK版本
  "compatibleSdkVersion": 12,

  // SDK类型
  "compatibleSdkType": "HarmonyOS",

  // 是否开启混淆
  "obfuscated": false,

  // 制品类型
  "artifactType": "original",

  // 模块描述
  "description": "应用主入口模块",

  // 模块入口文件
  "main": "./src/main/ets/index.ets",

  // TypeScript类型声明
  "types": "./src/main/ets/index.d.ts",

  // 开源协议
  "license": "Apache-2.0",

  // 作者
  "author": "demo",

  // 运行时依赖
  "dependencies": {

    // 系统能力依赖
    "@ohos/ability": "1.0.0",

    "@ohos/common": "1.2.0",

    // 本地模块依赖
    "app_store": "file:../app_store"
  },

  // 开发依赖
  "devDependencies": {

    // 测试框架
    "@ohos/hypium": "1.0.21"
  },

  // 动态依赖
  "dynamicDependencies": {}
}

核心字段说明

字段	作用
name	模块唯一标识
version	模块版本
main	模块入口文件
dependencies	运行时依赖
devDependencies	开发依赖
dynamicDependencies	动态HSP依赖

11. entry/src/main/module.json5

路径

entry/src/main/module.json5

定义

Stage模型核心配置文件

类似 Android：

AndroidManifest.xml 它是 HarmonyOS 最核心的配置文件之一。

用于定义：

Ability
页面路由
权限
设备支持
ExtensionAbility
服务卡片
URL拉起
元数据

系统安装与调度应用时会直接读取此文件。

完整配置模板

{
  "module": {

    // 模块名称
    "name": "entry",

    // 模块类型
    // entry：主模块
    // feature：动态特性模块
    // har：静态共享包
    // shared：动态共享包
    "type": "entry",

    // 模块描述
    "description": "$string:module_desc",

    // AbilityStage入口
    "srcEntry": "./ets/entryability/AbilityStage.ets",

    // 主UIAbility
    "mainElement": "EntryAbility",

    // 支持设备类型
    "deviceTypes": [
      "phone",
      "tablet"
    ],

    // 是否安装时一起安装
    "deliveryWithInstall": true,

    // 是否支持免安装
    "installationFree": false,

    // 是否压缩so库
    "compressNativeLibs": true,

    // URL Scheme白名单
    "querySchemes": [
      "demo"
    ],

    // 页面路由配置文件
    "pages": "$profile:main_pages",

    // 环境变量
    "appEnvironments": [
      {
        "name": "API_BASE_URL",

        "value": "https://api.example.com"
      }
    ],

    // UIAbility列表
    "abilities": [
      {
        // Ability名称
        "name": "EntryAbility",

        // Ability入口
        "srcEntry": "./ets/entryability/EntryAbility.ets",

        // 应用名称
        "label": "$string:EntryAbility_label",

        // 应用图标
        "icon": "$media:app_icon",

        // 是否允许其他应用调用
        "exported": true,

        // 启动页图标
        "startWindowIcon": "$media:start_icon",

        // 启动页背景
        "startWindowBackground": "$color:start_bg",

        // 技能匹配
        "skills": [
          {
            // 实体
            "entities": [
              "entity.system.home"
            ],

            // 行为
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],

    // 扩展Ability
    "extensionAbilities": [],

    // 服务卡片
    "forms": [],

    // 权限申请
    "requestPermissions": [
      {
        // 权限名
        "name": "ohos.permission.INTERNET",

        // 权限申请原因
        "reason": "$string:perm_internet_reason",

        // 使用场景
        "usedScene": {

          // 哪些Ability使用
          "abilities": [
            "EntryAbility"
          ],

          // 使用时机
          // inuse：使用中
          // always：始终
          "when": "inuse"
        }
      }
    ],

    // 元数据
    "metadata": []
  }
}

module.json5 核心作用

配置项	作用
abilities	UIAbility注册
pages	页面路由
requestPermissions	权限声明
extensionAbilities	后台扩展能力
forms	服务卡片
deviceTypes	支持设备
skills	系统拉起规则

12. obfuscation-rules.txt

路径

entry/obfuscation-rules.txt

定义

ArkTS / Native 混淆规则文件

类似 Android：

proguard-rules.pro 用于：

代码混淆
类名保护
方法保护
防止反射失效

完整配置模板

四、资源与路由

# 保持类名 
-keep class com.example.** { *; }  
# 保持注解 
-keepattributes *Annotation*  
# 保持资源类 
-keepclassmembers class **.R$* {     public static <fields>; }  
# 不警告指定包 
-dontwarn android.support.**  
# 保持Ability 
-keep class * extends ohos.aafwk.ability.UIAbility {     *; }  
# 保持ExtensionAbility 
-keep class * extends ohos.aafwk.ability.ExtensionAbility {     *; }

13. main_pages.json

路径

resources/base/profile/main_pages.json

定义

页面路由表配置文件

用于：

注册页面
页面跳转索引
路由管理

完整配置模板

{
  "src": [

    // 首页
    "pages/index/index",

    // 详情页
    "pages/detail/detail",

    // 设置页
    "pages/settings/settings"
  ]
}

页面跳转示例

router.pushUrl({
  url: "pages/detail/detail"
})

14. resources 资源体系

目录结构

resources/ ├── base/ │ ├── element/ │ ├── media/ │ └── profile/ ├── zh_CN/ ├── en_US/

element 资源目录

string.json

字符串资源

{
  "string": [
    {
      "name": "app_name",
      "value": "HarmonyDemo"
    }
  ]
}

color.json

颜色资源

{
  "color": [
    {
      "name": "main_color",
      "value": "#007DFF"
    }
  ]
}

float.json

尺寸资源

{
  "float": [
    {
      "name": "text_size",
      "value": "16fp"
    }
  ]
}

media 资源目录

用于存放：

png
jpg
svg
mp3
视频
动画

示例：

resources/base/media/ ├── app_icon.png ├── start_icon.png └── banner.jpg

profile 资源目录

用于存放：

页面路由
隐私配置
业务Profile

示例：

resources/base/profile/ ├── main_pages.json └── privacy_config.json

五、Native 与扩展

15. CMakeLists.txt

路径

src/main/cpp/CMakeLists.txt

定义

Native C/C++ 编译配置文件

用于：

编译so库
配置NDK
链接系统库

完整配置模板

# CMake最低版本
cmake_minimum_required(VERSION 3.5.0)

# 工程名称
project(MyNativeModule)

# 创建动态库
add_library(
    native_lib
    SHARED
    native.cpp
)

# 查找系统库
find_library(
    hilog-lib
    hilog_ndk.z
)

# 链接库
target_link_libraries(
    native_lib
    PUBLIC
    ${hilog-lib}
)

16. cjpm.toml

定义

仓颉语言包管理配置文件

类似：

Cargo.toml

完整配置模板

[package] name = "demo" version = "0.1.0" edition = "2024" [dependencies] std = "0.1.0"

六、完整配置体系总览

层级	文件	核心作用
应用级	AppScope/app.json5	应用全局配置
应用级	AppScope/pac.json5	隐私清单
工程级	build-profile.json5	全局构建
工程级	oh-package.json5	工程依赖
工程级	hvigor-config.json5	构建工具配置
工程级	hvigorfile.ts	构建脚本
工程级	code-linter.json5	代码规范
模块级	entry/build-profile.json5	模块构建
模块级	entry/oh-package.json5	模块依赖
模块级	module.json5	Ability与权限
模块级	obfuscation-rules.txt	混淆规则
资源级	main_pages.json	页面路由
资源级	resources/base	资源管理
Native	CMakeLists.txt	C/C++构建
仓颉	cjpm.toml	仓颉包管理

七、最核心的三个配置文件

文件	地位	类比 Android
module.json5	系统入口核心	AndroidManifest.xml
build-profile.json5	构建核心	build.gradle
app.json5	应用身份证	applicationId + manifest