前言

在前两天的学习中，我们成功创建并运行了第一个 HarmonyOS 应用，并对 DevEco Studio 的基本操作有了初步掌握。今天，我们将深入鸿蒙应用的“骨架”——项目目录结构与核心配置文件，系统性地理解一个 HarmonyOS 应用是如何组织、配置和运行的。

这些看似“幕后”的文件，实则决定了应用的入口、权限、页面路由、设备兼容性等关键行为。掌握它们，是迈向高级开发的第一步。

一、HarmonyOS 项目整体结构概览

一个典型的 HarmonyOS 应用（基于 ArkTS）项目结构如下：

MyApplication/
├── entry/                     ← 主模块（必须存在）
│   ├── src/
│   │   └── main/
│   │       ├── ets/           ← ArkTS 源代码（页面、组件、逻辑）
│   │       ├── resources/     ← 资源文件（字符串、图片、布局、配置）
│   │       └── module.json5   ← 模块级配置文件
│   └── build-profile.json5    ← 构建配置
├── hvigorfile.ts              ← 构建脚本（类似 Gradle）
├── oh-package.json5           ← 项目级依赖与元信息
└── AppScope/
    └── app.json5              ← 应用全局配置文件

💡 HarmonyOS 应用采用 多模块架构，entry 是默认的主模块（Entry Module），也可添加 feature 模块实现功能拆分。

二、核心配置文件详解

1. app.json5 —— 应用全局配置

路径：AppScope/app.json5
作用：定义整个应用的全局属性，如应用名称、图标、版本号、支持的设备类型等。

{
  "app": {
    "bundleName": "com.example.myapplication", // 应用唯一标识（包名）
    "vendor": "example",                       // 开发者厂商
    "versionCode": 100,                        // 内部版本号（整数，用于升级判断）
    "versionName": "1.0.0",                    // 对外显示的版本名称
    "icon": "$media:app_icon",                 // 应用图标（引用 resources/media 下的资源）
    "label": "$string:app_name",               // 应用名称（引用字符串资源）
    "description": "$string:app_desc",
    "minAPIVersion": 10,                       // 最低支持的 API 版本
    "targetAPIVersion": 11,                    // 目标 API 版本
    "debug": false                             // 是否为调试模式
  }
}

常见修改场景：

• 更换应用名称：修改 resources/base/element/string.json 中的 app_name 值；
• 更换图标：将新图标（如 icon.png）放入 resources/base/media/，并在 app.json5 中引用 $media:icon；
• 升级版本：发布新版本时，需同时增加 versionCode（如 101）和 versionName（如 "1.0.1"）。

2. module.json5 —— 模块级配置

路径：entry/src/main/module.json5
作用：配置当前模块的能力、页面、权限、设备类型等。

{
  "module": {
    "name": "entry",                          // 模块名称
    "type": "entry",                          // 模块类型（entry / feature）
    "mainElement": "Index",                   // 入口 UI 组件名（对应 Index.ets）
    "deviceTypes": ["phone", "tablet"],       // 支持的设备类型
    "deliveryWithInstall": true,              // 是否随应用安装
    "installationFree": false,
    "pages": "$profile:main_pages",           // 页面路由配置文件引用
    "requestPermissions": [                   // 声明所需权限
      {
        "name": "ohos.permission.INTERNET"
      }
    ],
    "abilities": [                            // 能力（Ability）声明
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true
      }
    ]
  }
}

关键字段说明：

• pages: 引用 resources/base/profile/main_pages.json，定义可路由的页面列表；
• abilities: 声明应用的“能力单元”，HarmonyOS 中每个 UI 入口对应一个 Ability；
• requestPermissions: 若需网络、位置等敏感权限，必须在此声明，否则运行时会报错。

3. main_pages.json —— 页面路由清单

路径：entry/src/main/resources/base/profile/main_pages.json
作用：列出该模块中所有可被导航的页面路径（相对于 ets 目录）。

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

⚠️ 注意： 路径不带 .ets 后缀； 新增页面后必须在此注册，否则无法通过 router.pushUrl() 跳转； 页面文件需放在 ets/pages/ 目录下（约定优于配置）。

例如，若你创建了 Profile.ets，需添加 "pages/Profile" 才能使用：

import router from '@ohos.router';

// 跳转到 Profile 页面
router.pushUrl({ url: 'pages/Profile' });

4. 资源文件：resources/ 目录

HarmonyOS 推荐将字符串、颜色、尺寸、媒体等资源集中管理，便于多语言、多设备适配。

• resources/base/element/string.json：应用名称、提示文本等 { "string": [ { "name": "app_name", "value": "我的鸿蒙应用" }, { "name": "welcome_text", "value": "欢迎使用！" } ] } 在代码中引用：$r('app.string.welcome_text')
• resources/base/media/：存放图标、启动图等（如 app_icon.png）
• resources/base/profile/：存放配置类 JSON 文件（如 main_pages.json）

三、配置修改实战：自定义应用信息

假设我们要将应用改为“天气助手”，步骤如下：

1. 修改应用名称编辑 resources/base/element/string.json： { "name": "app_name", "value": "天气助手" }
2. 更换图标 将 weather_icon.png 放入 resources/base/media/ 修改 app.json5 中的 icon 字段："icon": "$media:weather_icon"
3. 添加新页面并注册路由 创建 ets/pages/Weather.ets 在 main_pages.json 中添加："src": ["pages/Index", "pages/Weather"]
4. 申请网络权限（用于获取天气数据）在 module.json5 的 requestPermissions 中加入： { "name": "ohos.permission.INTERNET" }

完成以上修改后，重新运行应用，即可看到新名称、新图标，并具备访问网络的能力。

四、常见配置错误与排查