Flutter OpenHarmony化工程的目录结构详解

在Flutter向OpenHarmony生态适配的过程中，标准化的工程目录结构 是保障跨端开发效率、工程可维护性的核心基础。Flutter OpenHarmony化（下称Flutter-OH）工程在保留原生Flutter跨端特性的同时，融入了OpenHarmony工程的官方目录规范，核心通过ohos/目录承载鸿蒙端所有配置与原生代码，与Flutter的lib/等跨端目录解耦，实现"一次开发，多端运行"的适配目标。

本文将详细梳理Flutter-OH工程的核心目录结构，并对鸿蒙端关键配置文件、代码文件的作用与核心能力做精准解析，帮助开发者快速掌握Flutter-OH工程的目录组织逻辑，降低鸿蒙端适配与开发成本。

一、Flutter-OH工程整体目录结构

Flutter-OH工程的目录核心分为Flutter跨端通用层 和OpenHarmony原生适配层 ，其中ohos/目录是鸿蒙端的核心，所有鸿蒙端的配置、原生代码、资源均集中在此，由flutter-oh create -t app_ohos .命令自动生成，无需手动创建，有效避免目录结构混乱。

标准化的Flutter-OH工程目录结构如下（核心目录/文件标粗）：

复制代码

flutter_oh_demo/          # Flutter-OH工程根目录
├── lib/                  # Flutter核心Dart代码（跨端通用，无需修改）
├── pubspec.yaml          # Flutter工程依赖配置（需添加ohos平台声明）
├── test/                 # Flutter单元测试目录（跨端通用）
├── example/              # 示例工程目录（可选，按需保留）
└── **ohos/**             # OpenHarmony端核心适配目录（Flutter-OH核心）
    ├── **AppScope/**     # 鸿蒙工程全局作用域（官方标配）
    │   └── **app.json5** # 应用全局核心配置文件
    ├── **entry/**        # 鸿蒙主入口模块（默认唯一模块，核心载体）
    │   ├── **build-profile.json5** # 模块构建配置文件
    │   ├── **oh-package.json5**    # 模块依赖配置文件
    │   └── src/
    │       └── main/     # 模块主源码/配置根目录
    │           ├── **entryability/** # 鸿蒙应用入口能力目录
    │           │   └── **EntryAbility.ets** # 鸿蒙端应用入口文件
    │           ├── **pages/**        # 鸿蒙页面组件目录
    │           │   └── **Index.ets** # 鸿蒙端默认首页面（Flutter渲染容器）
    │           ├── resources/        # 鸿蒙资源目录（图片/布局/字符串，可选）
    │           └── **module.json5**  # 鸿蒙模块核心配置文件
    ├── **build-profile.json5**       # 鸿蒙工程全局构建配置文件
    └── **oh-package.json5**          # 鸿蒙工程全局依赖配置文件

从目录结构能清晰看到：Flutter的lib/、pubspec.yaml等目录文件完全保留，与鸿蒙端ohos/目录相互独立，适配时仅需关注鸿蒙端目录的配置与开发，无需修改任何Flutter跨端Dart代码，最大程度降低适配成本。

二、Flutter-OH工程鸿蒙端关键文件解析

Flutter-OH工程的鸿蒙端关键文件分为配置文件 和核心代码文件两类，其中配置文件按「工程级（全局生效）」和「模块级（仅entry模块生效）」划分，贴合OpenHarmony官方工程的配置规范，代码文件则是Flutter与OpenHarmony原生衔接的核心载体。

（一）配置文件：管控鸿蒙端工程/模块的核心规则

配置文件均为OpenHarmony官方标准的json5格式，支持注释、换行等更友好的编写方式，是鸿蒙端工程构建、运行、打包的基础，直接决定工程的基础属性、依赖管理、构建规则。

1. 工程级配置文件（ohos/根目录，全局生效）

工程级配置文件管控整个Flutter-OH鸿蒙端工程的全局属性，所有模块（如默认的entry模块）均继承此层级的配置，修改后影响整个鸿蒙端工程。

文件路径	配置级别	核心作用
ohos/AppScope/app.json5	工程级	应用全局唯一配置，包含包名、开发厂商、应用版本号、全局权限声明等核心基础信息
ohos/build-profile.json5	工程级	工程全局构建配置，定义编译模式（debug/release）、OH SDK版本、构建产物路径等
ohos/oh-package.json5	工程级	工程全局依赖配置，管理跨模块的公共三方库、开发工具依赖等

2. 模块级配置文件（ohos/entry/目录，仅主模块生效）

entry模块是Flutter-OH鸿蒙端的唯一主入口模块，模块级配置文件仅管控该模块的属性，是Flutter页面在鸿蒙端渲染的核心配置载体，适配时需重点关注此层级配置。

文件路径	配置级别	核心作用
ohos/entry/build-profile.json5	模块级	模块构建配置，关联工程级构建规则，定义模块专属编译参数、依赖引用规则等
ohos/entry/oh-package.json5	模块级	模块本地依赖配置，管理entry模块专属的鸿蒙三方库、原生组件依赖等
ohos/entry/src/main/module.json5	模块级	模块核心元信息配置，包含模块名称、类型、支持设备类型、页面路由、局部权限声明等

关键注意 ：所有配置文件的包名、OH SDK版本 需保持统一------包名需与Flutter工程pubspec.yaml中ohos平台配置的default_package一致，OH SDK版本建议选择API 20/21/22（Flutter-OH主流兼容版本）。

（二）核心代码文件：Flutter与鸿蒙端的衔接核心

鸿蒙端的核心代码文件基于OpenHarmony的ETS语言开发，是Flutter引擎初始化 和Flutter页面渲染承载的关键，仅需少量修改即可完成Flutter代码与鸿蒙端的衔接，是Flutter-OH适配的核心代码层。

文件路径	核心作用	适配关键要点
ohos/entry/src/main/entryability/EntryAbility.ets	鸿蒙端应用唯一入口文件，负责应用初始化、生命周期管理、Flutter引擎初始化	需在此文件中完成Flutter引擎的初始化，关联Flutter的根页面
ohos/entry/src/main/pages/Index.ets	鸿蒙端默认首页面，Flutter页面的渲染容器载体	需在页面中引入Flutter容器组件，将Flutter的Dart页面嵌入鸿蒙端页面

核心逻辑 ：当鸿蒙端应用启动时，首先执行EntryAbility.ets完成Flutter引擎的初始化，随后跳转到Index.ets页面，通过该页面中的Flutter容器组件，将Flutterlib/目录中的Dart页面渲染到鸿蒙端，实现Flutter代码在OpenHarmony设备上的运行。

三、Flutter-OH工程目录与文件的核心使用原则

目录解耦，各司其职 ：Flutter跨端代码（lib/）与鸿蒙端原生代码（ohos/）完全解耦，开发/适配时切勿在Flutter目录中添加鸿蒙端代码，避免工程混乱；
自动生成，禁止手动修改基础结构 ：鸿蒙端ohos/目录及所有核心文件由flutter create命令行工具自动生成，切勿手动删除/修改基础目录结构，仅需在指定文件中做个性化配置与开发；
配置统一，版本兼容：所有配置文件的包名、OH SDK版本、Flutter-OH版本需保持一致，建议选择API 20/22的OH SDK，兼容绝大多数OpenHarmony设备；
资源隔离，单独管理 ：鸿蒙端的图片、布局、字符串等资源需放在ohos/entry/src/main/resources/目录，与Flutter的assets/资源目录隔离，分别按各自生态的规范管理；
最小化修改，聚焦核心衔接 ：鸿蒙端仅需修改EntryAbility.ets和Index.ets两个核心代码文件，即可完成Flutter与鸿蒙端的衔接，无需额外开发原生代码，降低适配门槛。

四、总结

Flutter OpenHarmony化工程的目录结构，是Flutter跨端生态 与OpenHarmony原生生态 的融合产物，核心通过ohos/目录承载鸿蒙端所有配置与原生代码，与Flutter原有目录解耦，既保留了Flutter"一次开发，多端运行"的核心优势，又贴合OpenHarmony的官方工程规范。

本文梳理的鸿蒙端关键配置文件和核心代码文件，是Flutter-OH工程运行的基础------配置文件决定了鸿蒙端工程的基础属性与构建规则，代码文件则实现了Flutter引擎与鸿蒙端的衔接、Flutter页面的渲染承载。掌握这些目录与文件的作用及使用原则，能帮助开发者快速上手Flutter-OH工程的开发与适配，高效完成Flutter项目向OpenHarmony生态的迁移。

后续我们还将针对Flutter-OH工程的核心配置修改 、Flutter引擎初始化 、页面渲染衔接等关键环节做详细实战讲解，敬请关注！

欢迎大家加入开源鸿蒙跨平台开发者社区：https://openharmonycrossplatform.csdn.net/