系列：HarmonyOS 开发入门 · 02

第一次打开 HarmonyOS 工程，很容易有一种“文件不少，但不知道先看哪个”的感觉。

我自己的习惯是先把工程分成三层：工程级、Module 级、源码级。这样再看 build-profile.json5、module.json5、oh-package.json5，就不会全混在一起。

1. 先看一份最小目录

一个常见的应用工程大致长这样：

MyApplication
├── AppScope
│   └── app.json5
├── entry
│   ├── src
│   │   └── main
│   │       ├── ets
│   │       │   ├── entryability
│   │       │   └── pages
│   │       ├── resources
│   │       └── module.json5
│   ├── oh-package.json5
│   └── build-profile.json5
├── build-profile.json5
└── oh-package.json5

看着多，其实职责很明确。

2. AppScope：应用级配置

AppScope/app.json5 可以理解为“整个应用”的基本信息入口。

应用名称、图标、版本等应用级信息通常会在这个层级体现。

要注意：应用级配置和模块级配置不是一回事。

一个应用可以有多个模块，所以不能把所有东西都塞到 module.json5 里理解。

3. entry：默认主模块

新建普通工程时，一般会看到一个 entry 模块。

它通常是应用主入口 HAP 所在的位置，也是刚入门时改动最多的目录。

真正的业务代码主要在：

entry/src/main/ets

例如：

ets
├── entryability
│   └── EntryAbility.ets
└── pages
    └── Index.ets

EntryAbility.ets 负责 UIAbility 相关生命周期和窗口内容加载；pages 下放页面。

项目变大以后，我不建议所有代码都继续堆在 pages 里，后续一般会拆成 features、components、services、models 等目录。

4. module.json5：这个 Module 能做什么

module.json5 是一个非常关键的文件。

你可以把它理解成：

这个模块是谁、包含哪些 Ability、申请了什么权限、有哪些页面或路由能力。

很多问题最后都会回到这里，比如：

• 权限明明写代码申请了，为什么不弹？
• UIAbility 为什么启动不了？
• 路由表为什么没有生效？

例如使用 Navigation 系统路由表时，需要在 module.json5 中注册：

{
  "module": {
    "routerMap": "$profile:router_map"
  }
}

这也是为什么我经常说：鸿蒙开发不能只盯着 .ets 文件看。

5. resources：不要把所有文本写死在代码里

资源目录通常类似：

resources
├── base
│   ├── element
│   ├── media
│   └── profile
└── rawfile

element 常放字符串、颜色等资源；media 放图片；profile 放一些配置型资源；rawfile 放原始资源文件。

例如界面文本更推荐走资源：

Text($r('app.string.app_name'))

而不是整个项目到处写：

Text('我的应用')

后面做多语言时，你会感谢现在没有偷懒。

6. 两个 build-profile.json5 为什么都有

这是新人很容易混淆的地方。

工程根目录有一份：

/build-profile.json5

模块下面还有一份：

/entry/build-profile.json5

可以简单理解：

• 工程级：管理整个工程的构建目标、产品等；
• Module 级：管理当前模块的具体构建配置。

比如 Debug 和 Release 是否开启混淆、模块构建模式差异，很多会落在构建配置里。

7. oh-package.json5：依赖管理

如果你写过 Node.js，可以把它类比成 package.json，但不要完全等同。

项目依赖和模块依赖都可能有各自的 oh-package.json5。

例如添加一个三方库后，通常会在这里看到依赖记录。

对应的包管理工具是 ohpm。

8. 我建议的阅读顺序

接手一个陌生 HarmonyOS 工程时，我通常不会从 Index.ets 一头扎进去，而是按这个顺序：

app.json5
↓
module.json5
↓
build-profile.json5
↓
EntryAbility.ets
↓
Navigation / 首页
↓
业务模块

这样能很快判断：应用结构是什么、入口在哪、页面怎么组织、权限和模块怎么配。

9. 一个常见误区

很多初学者把 HarmonyOS 工程理解成“ArkTS 页面集合”。

实际上真正的应用是：

配置 + Ability + UI + 系统能力 + 构建产物

页面只是其中一层。

当以后遇到签名、权限、跨模块路由、HAP/HSP/HAR、不同构建环境时，这个认知会非常重要。

总结

刚开始只需要记住：

• AppScope：应用级；
• entry：主模块；
• ets：ArkTS 源码；
• resources：资源；
• module.json5：模块能力配置；
• build-profile.json5：构建配置；
• oh-package.json5：依赖。

下一篇开始聊 ArkTS。很多从前端或 TypeScript 转过来的开发者，第一反应都是“这不就是 TS 吗？”——实际写起来并不是。