HarmonyOS 小游戏《对战五子棋》开发第3篇-项目配置文件全解析

从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

// 项目级构建脚本exportdefault{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管显示内容

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

附：