从build-profile到oh-package，读懂鸿蒙项目的每一行配置

配置文件全景图

五子棋/
├── build-profile.json5          ← 项目级构建配置
├── oh-package.json5             ← 项目级依赖管理
├── hvigorfile.ts                ← 构建脚本
├── hvigor/hvigor-config.json5   ← Hvigor配置
├── AppScope/app.json5           ← 应用清单
├── entry/
│   ├── build-profile.json5      ← 模块级构建配置
│   ├── oh-package.json5         ← 模块级依赖管理
│   └── src/main/module.json5    ← 模块清单

build-profile.json5（项目级）

{
  "app": {
    "signingConfigs": [],           // 签名配置
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",  // 兼容SDK版本
        "runtimeOS": "HarmonyOS",              // 运行时OS
        "targetSdkVersion": "6.1.1(24)"        // 目标SDK版本
      }
    ],
    "buildModeSet": [
      { "name": "debug" },          // 调试模式
      { "name": "release" }         // 发布模式
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    }
  ]
}

关键字段解读：

• compatibleSdkVersion：应用最低支持的SDK版本，低于此版本的设备无法安装
• targetSdkVersion：应用目标SDK版本，决定可用的API范围
• products：可以定义多个产品（如免费版/付费版），每个产品可以有不同的签名和配置
• buildModeSet：构建模式，debug用于开发调试，release用于发布

oh-package.json5（项目级）

{
  "modelVersion": "6.1.1",
  "description": "Gomoku game for HarmonyOS",
  "dependencies": {},
  "devDependencies": {
    "@ohos/hypium": "1.0.21"
  }
}

• modelVersion：包管理模型版本
• dependencies：运行时依赖
• devDependencies：开发时依赖（如测试框架）
• @ohos/hypium：华为官方单元测试框架

entry/build-profile.json5（模块级）

{
  "apiType": "stageMode",
  "buildOption": {},
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    }
  ]
}

apiType有两个选项：

• stageMode：Stage模型（推荐，本项目使用）
• faMode：FA模型（旧版，不推荐）

entry/oh-package.json5（模块级）

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Gomoku entry module",
  "main": "",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {}
}

hvigorfile.ts

// 项目级构建脚本
export default {
  system: require('@ohos/hvigor-ohos-plugin').hapTasks
}

Hvigor是鸿蒙的构建工具，使用TypeScript编写构建脚本，比Gradle的Groovy更易调试。

配置文件之间的关系

app.json5 (应用身份)
    ↓ 定义了应用级别信息
module.json5 (模块能力)
    ↓ 定义了模块的Ability和页面
main_pages.json (页面路由)
    ↓ 注册了所有页面路径
build-profile.json5 (构建规则)
    ↓ 定义了如何编译
oh-package.json5 (依赖管理)
    ↓ 定义了项目依赖

实际开发中的常见配置场景

1. 修改应用名称

编辑AppScope/resources/base/element/string.json：

{ "name": "app_name", "value": "五子棋" }

2. 添加新页面

在main_pages.json中注册：

{ "src": ["pages/Index", "pages/NewPage"] }

3. 修改启动背景色

编辑entry/src/main/resources/base/element/color.json：

{ "name": "start_window_background", "value": "#F5F5DC" }

4. 适配深色模式

创建dark/element/color.json覆盖特定颜色：

{ "name": "start_window_background", "value": "#333333" }

总结

鸿蒙项目的配置虽然文件多，但每个文件职责单一：

• app.json5管应用身份
• module.json5管模块能力
• build-profile.json5管构建规则
• oh-package.json5管依赖
• 资源json管显示内容

理解这些配置文件的职责边界，是高效开发鸿蒙应用的基础。

附：