适合谁看

• 第一次打开 app/ohos/ 的 Flutter 开发者

• 想快速定位关键文件的人

• 不想被构建缓存和杂项目录分散注意力的人

问题背景

很多 Flutter 开发者第一次接触鸿蒙壳工程时，会有一种很常见的感觉：

目录看起来不算特别复杂，但不知道到底先读哪个文件。

这其实不是因为文件太多，而是因为 app/ohos/ 里混合了不同层级的内容：

• 构建层

• 依赖层

• 模块声明层

• Ability 入口层

• 插件层

• 卡片层

如果没有优先级，阅读很容易陷入两个误区：

• 一上来就盯着某个 json5，结果只看到局部

• 时间花在次要目录上，主线结构反而没建立起来

项目中的真实场景

食界探味现在的鸿蒙目录已经具备了很典型的阅读样本。
真正高频需要理解的关键位置，其实集中在少数几个文件和目录：

• app/ohos/build-profile.json5

• app/ohos/oh-package.json5

• app/ohos/entry/src/main/module.json5

• app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

• app/ohos/entry/src/main/ets/plugins/

• app/ohos/entry/src/main/ets/formability/

而像真正把 Flutter 页面挂进鸿蒙容器的页面壳，也在：

• app/ohos/entry/src/main/ets/pages/Index.ets

核心实现

如果你第一次进入 app/ohos/，我更建议先用“关键程度”而不是“目录层级”来读。

第一批必须先看的：决定工程能否成立的文件

1. app/ohos/build-profile.json5

这个文件更接近构建和签名层。
在食界探味里，你能直接看到：

• signingConfigs

• products

• buildModeSet

• modules

它回答的是：

• 这个鸿蒙工程怎么构建

• 用哪套签名配置

• 模块如何被挂进产品

如果你后面遇到的是构建、签名、profile 相关问题，这个文件通常是第一站。

2. app/ohos/oh-package.json5

这个文件更接近鸿蒙依赖层。
在食界探味里，它现在内容不算复杂，但角色很明确：

• 声明工程名和版本

• 管理 Ohos 侧依赖和开发依赖

它回答的是：

• 鸿蒙模块依赖从哪里来

• 当前工程的 Ohos 依赖生态怎么组织

3. app/ohos/entry/src/main/module.json5

这是 app/ohos/ 里最应该优先理解的单文件之一。
因为它相当于整个入口模块的说明书。

在食界探味里，这个文件里最值得先看的是：

• mainElement: "EntryAbility"

• abilities

• extensionAbilities

• requestPermissions

你从这里就能很快看出：

• 应用主入口是谁

• 卡片能力有没有接进来

• 权限声明了哪些

如果说 build-profile.json5 决定“怎么构建”，那 module.json5 决定的就是“这个模块到底是什么”。

第二批必须先看的：决定应用怎么进来的文件

4. app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

这个文件是理解鸿蒙壳工程最重要的入口代码之一。

在食界探味里，它至少做了三件关键的事：

• configureFlutterEngine 里注册 Flutter 插件和自定义原生插件

• onCreate 里承接系统带进来的参数

• onNewWant 里处理应用运行中再次到来的导航意图

换句话说，它不是单纯的“启动文件”，而是：

• Flutter 引擎挂载点

• 系统参数承接点

• 应用入口生命周期协调点

5. app/ohos/entry/src/main/ets/pages/Index.ets

很多人第一次读壳工程时会忽略这个文件，因为它看上去代码不多。
但它的意义很清楚：它负责把 FlutterPage 真正挂到鸿蒙页面容器里。

在食界探味里，它最值得注意的是：

• FlutterPage({ viewId: this.viewId })

• onBackPress() 把返回事件回送给 Flutter

这说明页面壳本身虽然轻，但位置很关键。

第三批再看的：决定系统能力和系统触达的目录

6. app/ohos/entry/src/main/ets/plugins/

这是系统能力实现层。
在食界探味里，这里已经包括：

• SpeechRecognitionPlugin.ets

• TextToSpeechPlugin.ets

• IntentNavigationPlugin.ets

• AntiPeepProtectionPlugin.ets

• GeneratedPluginRegistrant.ets

其中 GeneratedPluginRegistrant.ets 说明 Flutter 生态插件的 Ohos 注册方式，
而其他几个文件则是项目自定义的原生能力实现。

如果你想看：

• 语音识别怎么接

• TTS 怎么接

• Intent 怎么承接

• 防窥怎么订阅

这一层就是后面的重点阅读区。

7. app/ohos/entry/src/main/ets/formability/

这是卡片能力层。
在食界探味里，核心文件包括：

• DailyRecommendFormAbility.ets

• RecommendData.ets

它们说明这个项目不只是能启动应用，还已经接入了 Form Kit 风格的桌面卡片能力。

第四批再看的：理解系统入口延伸能力的文件

8. app/ohos/entry/src/main/ets/entryability/InsightIntentExecutorImpl.ets

如果你只想先把应用跑起来，这个文件不是第一批必须读的。
但如果你要理解鸿蒙和普通 Flutter App 的真正差别，它又非常关键。

因为它承接的是：

• 系统搜索

• 意图直达

• 外部入口导航

它和 EntryAbility.ets 一起，把“应用入口”从单点扩展成了一组系统入口。

关键代码位置

• app/ohos/build-profile.json5

• app/ohos/oh-package.json5

• app/ohos/entry/src/main/module.json5

• app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

• app/ohos/entry/src/main/ets/pages/Index.ets

• app/ohos/entry/src/main/ets/plugins/

• app/ohos/entry/src/main/ets/formability/

鸿蒙侧实现

从鸿蒙侧看，app/ohos/ 里的关键文件其实可以压缩成四层：

• 构建层：build-profile.json5

• 依赖层：oh-package.json5

• 模块声明层：module.json5

• 代码承接层：entryability/、pages/、plugins/、formability/

只要先把这四层对上，后面很多配置和代码阅读都会简单很多。

Flutter 侧实现

Flutter 侧虽然不直接写这些文件，但会持续依赖它们：

• app/lib/core/platform/ 需要知道原生能力落在哪

• 页面层需要依赖壳工程正确承接系统入口

• 平台能力需要依赖插件层存在

所以理解 app/ohos/ 的关键文件，不是为了“会改原生”，而是为了知道 Flutter 对接的到底是哪一层。

常见坑

• 没先区分构建文件、模块文件和入口代码

• 一上来就看插件实现，却还不知道入口是怎么起来的

• 把 Index.ets 这种轻文件误判成不重要

• 在没理解 module.json5 的情况下就开始查权限问题

可复用模板

第一次读 app/ohos 的顺序
1. build-profile.json5       # 先知道怎么构建
2. oh-package.json5          # 再知道依赖在哪里
3. module.json5              # 再知道模块声明了什么
4. EntryAbility.ets          # 再看入口怎么接
5. Index.ets                 # 再看 Flutter 页面怎么挂
6. plugins/ formability/     # 最后看能力实现和卡片

关键文件四分法
- 构建文件
- 依赖文件
- 模块说明书
- 入口与能力代码

本篇总结

app/ohos/ 不是每个文件都同等重要。
第一次读时，最稳的方式不是“从上到下扫目录”，而是先抓住：

• 构建层

• 依赖层

• 模块声明层

• 入口与能力层

只要这几层先对上，后面再去读语音、TTS、Intent、卡片这些具体实现，就不会总在目录里打转了。