【2026 最新】Flutter 编译开发 OpenHarmony 工程目录结构全解析

目录总览（根目录）

• .dart_tool/
• .idea/
• build/
• lib/
• ohos/
• test/
• .gitignore
• .metadata
• README.md
• analysis_options.yaml
• flutter_harmonyos.iml
• pubspec.lock
• pubspec.yaml

说明：部分目录（如 .dart_tool/、build/、node_modules/）为工具生成的缓存/构建产物，通常不需要手工修改。

---

Flutter（Dart）侧

lib/

• 作用：Flutter 应用的主要 Dart 源码目录。UI、页面、状态管理、业务逻辑一般都放在这里。
• 当前包含 ：lib/main.dart
  • 作用 ：应用入口文件，包含 main() 与 runApp()，以及默认示例 MyApp/MyHomePage。
  • 你一般会在这里做什么 ：
    • 替换默认示例页面为你的真实首页
    • 配置路由、主题、国际化等

test/

• 作用：自动化测试目录（单元测试、Widget 测试等）。
• 当前包含 ：test/widget_test.dart
  • 作用 ：默认计数器示例的 Widget 测试（点击 + 后数值递增）。

pubspec.yaml

• 作用：Flutter/Dart 项目清单文件。
• 主要内容 ：
  • 项目元信息 ：name、description、version
  • Dart SDK 约束 ：environment.sdk
  • 依赖声明 ：dependencies、dev_dependencies
  • 资源配置 ：flutter 节点（如 assets、fonts、uses-material-design）
• 你一般会在这里做什么 ：
  • 新增/升级依赖
  • 配置图片、字体等资源

pubspec.lock

• 作用：锁定依赖的精确版本，保证不同机器/CI 拉取依赖一致。
• 修改方式 ：通常由 flutter pub get/upgrade 自动生成/更新。

analysis_options.yaml

• 作用：Dart 静态分析（Analyzer）与 lint 规则配置。
• 当前配置 ：包含 package:flutter_lints/flutter.yaml（Flutter 官方推荐规则集）。

.metadata

• 作用：Flutter 工程元数据（Flutter 工具链会使用）。
• 注意：一般不需要手改。

.dart_tool/

• 作用：Dart/Flutter 工具链生成目录（依赖解析、构建缓存等）。
• 注意：一般不提交、不手改。

build/

• 作用：Flutter 构建输出目录。
• 注意：构建产物目录，一般不提交。

README.md

• 作用：仓库说明文档入口。
• 当前内容：为 Flutter 默认模板生成的说明。

.gitignore

• 作用：Git 忽略规则，避免把构建产物、缓存、IDE 配置等提交到仓库。

.idea/ 与 flutter_harmonyos.iml

• 作用：IDE（JetBrains 系）工程配置文件。
• 注意：是否提交取决于团队约定；通常与个人环境相关。

---

OpenHarmony（ohos/）侧

ohos/ 目录包含 OpenHarmony 工程（Hvigor 构建），用于在 HarmonyOS 上承载/集成 Flutter 运行与打包。

ohos/hvigorfile.ts

• 作用：Hvigor 构建脚本入口（应用级别）。
• 你这份工程的关键点 ：
  • 引入 flutter-hvigor-plugin 并指向 Flutter 工程根目录（path.dirname(__dirname)）。
  • 这通常用于在 HarmonyOS 构建流程中注入 Flutter 相关的构建/产物处理逻辑。

ohos/hvigorconfig.ts

• 作用：Hvigor 配置脚本。
• 你这份工程的关键点 ：调用 injectNativeModules(...)，一般用于把 Flutter 相关 native 模块/依赖注入到 Harmony 工程。

ohos/oh-package.json5 与 ohos/oh-package-lock.json5

• 作用：OpenHarmony 工程级别的包管理描述与锁定文件。
• 你一般会在这里做什么：添加/锁定 OpenHarmony 侧依赖（如果工程需要）。

ohos/AppScope/

• 作用：应用级别的配置与全局资源。
• ohos/AppScope/app.json5 ：
  • 作用 ：应用包标识与版本等信息，例如：
    • bundleName：应用包名（com.example.flutter_harmonyos）
    • versionCode / versionName
    • icon / label

ohos/entry/

• 作用：主模块（通常是一个 HAP 模块）。
• 常见内容 ：
  • entry/src/main/：主模块源码与资源（应用启动、Ability/页面等通常在这里）
  • entry/src/ohosTest/：OpenHarmony 侧测试代码
  • entry/hvigorfile.ts：模块级构建脚本（你这份是默认 hapTasks，通常无需修改）
  • entry/build-profile.json5：构建 profile（声明 apiType、targets，如 default/ohosTest）
  • entry/oh-package.json5、entry/oh-package-lock.json5：模块级依赖描述/锁定

ohos/entry/ 其它常见关键文件

ohos/entry/hvigorfile.ts

• 作用 ：entry 模块（HAP）的 Hvigor 构建脚本入口。
• 你这份工程的关键点 ：使用 @ohos/hvigor-ohos-plugin 的内置 hapTasks，plugins: [] 为空。
• 你一般会在这里做什么 ：
  • 大多数 Flutter 集成项目不需要修改；只有当你需要扩展 HAP 构建行为（自定义打包步骤、资源处理）时才会添加插件。

ohos/entry/build-profile.json5

• 作用：声明构建目标与构建配置。
• 你这份工程的关键点 ：
  • apiType: 'stageMode'：Stage 模型。
  • targets：包含 default（runtimeOS: HarmonyOS）以及 ohosTest（测试目标）。

ohos/entry/oh-package.json5 与 ohos/entry/oh-package-lock.json5

• 作用 ：entry 模块的依赖描述与锁定（OpenHarmony 包管理）。
• 你这份工程的关键点 ：当前 dependencies 为空，属于模板/最小配置。

ohos/entry/src/main/（逐项说明）

该目录是 entry 模块的"主源码 + 主资源"目录，主要由 module.json5（模块配置）、ArkTS 源码（ets/）和资源（resources/）构成。

ohos/entry/src/main/module.json5

• 作用：模块清单/配置文件，声明模块类型、入口 Ability、页面路由列表、权限等。
• 你这份工程的关键点 ：
  • mainElement: "EntryAbility"：声明模块主入口 Ability。
  • abilities[0].srcEntry: "./ets/entryability/EntryAbility.ets"：Ability 的 ArkTS 入口源码。
  • pages: "$profile:main_pages"：页面路由配置来自资源 profile（对应 resources/base/profile/main_pages.json）。
  • requestPermissions：声明权限（你这份包含 ohos.permission.INTERNET，Flutter/网络请求常用）。

ohos/entry/src/main/ets/

• 作用：ArkTS/ArkUI 源码目录（Stage 模型下常见结构）。
• 你这份工程的目录 ：
  • ets/entryability/EntryAbility.ets
  • ets/pages/Index.ets
  • ets/plugins/（当前为空，通常用于生成或放置插件相关 ArkTS 代码）

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

• 作用：应用入口 Ability，实现"把 Flutter 引擎跑起来并注册插件"。
• 你这份工程的关键点 ：
  • extends FlutterAbility：该 Ability 由 @ohos/flutter_ohos 提供，用于承载 Flutter。
  • configureFlutterEngine(...)：在引擎创建/配置时注册插件：
    • GeneratedPluginRegistrant.registerWith(flutterEngine)
• 你一般会在这里做什么 ：
  • 当你新增/调整 Harmony 侧对 Flutter 引擎的初始化逻辑（例如引擎参数、Channel 初始化等）时会动这里。

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

• 作用 ：ArkUI 页面入口（UI 层），在页面中嵌入 FlutterPage 作为 Flutter 的渲染容器。
• 你这份工程的关键点 ：
  • @Entry(storage)：声明该组件为应用入口页面。
  • FlutterPage({ viewId: this.viewId })：实际承载 Flutter 视图。
  • onBackPress()：拦截返回键并通过 eventHub 发出 EVENT_BACK_PRESS 事件（用于把返回事件传递到 Flutter/或统一处理）。

ohos/entry/src/main/resources/

• 作用：OpenHarmony 资源目录（字符串、颜色、页面 profile、rawfile 等）。
• 你这份工程的目录 ：
  • resources/base/：默认资源（不分语言）。
  • resources/zh_CN/、resources/en_US/：多语言资源覆盖。
  • resources/rawfile/：原始文件资源（不经资源编译处理，按文件原样打包）。

ohos/entry/src/main/resources/base/profile/main_pages.json

• 作用：声明 ArkUI 页面路由列表。
• 你这份工程 ：配置了 pages/Index，对应 ets/pages/Index.ets。

ohos/entry/src/main/resources/base/element/string.json / zh_CN/element/string.json / en_US/element/string.json

• 作用：字符串资源（模块描述、Ability 名称等），支持多语言覆盖。
• 你这份工程的关键点 ：
  • module_desc、EntryAbility_desc、EntryAbility_label 等。
  • module.json5 中的 $string:... 就是引用这里的资源项。

ohos/entry/src/main/resources/base/element/color.json

• 作用：颜色资源。
• 你这份工程的关键点 ：start_window_background 供 module.json5 的 startWindowBackground 引用。

ohos/entry/src/main/resources/rawfile/flutter_assets/

• 作用 ：Flutter 资源打包输出目录（Flutter 的 assets、字体等会以特定结构放在这里供引擎加载）。
• 注意：通常由构建流程生成/同步，不建议手工修改其内容。

ohos/entry/src/main/resources/rawfile/buildinfo.json5

• 作用：Flutter 运行相关开关/配置（以 rawfile 形式随包携带）。
• 你这份工程的关键点 ：enable_impeller: true（启用 Impeller 渲染后端的开关）。

ohos/entry/src/main/resources/rawfile/framesconfig.json

• 作用 ：帧率/刷新率相关策略配置（按不同负载区间配置 preferred_fps 等）。
• 你这份工程的关键点：根据不同区间设置 60/72/90/120 fps。

ohos/entry/src/ohosTest/（逐项说明）

该目录是 entry 模块的 OpenHarmony 侧测试工程（通常用于 Hypium 单元测试、Ability 测试等）。

ohos/entry/src/ohosTest/module.json5

• 作用：测试模块清单/配置文件。
• 你这份工程的关键点 ：
  • name: "entry_test"、type: "feature"：测试模块定义。
  • mainElement: "TestAbility"：测试入口 Ability。
  • abilities[0].srcEntry: "./ets/testability/TestAbility.ets"：测试 Ability 的 ArkTS 入口。
  • pages: "$profile:test_pages"：测试页面路由来自 resources/base/profile/test_pages.json。

ohos/entry/src/ohosTest/ets/

• 作用：测试用 ArkTS 源码目录。
• 你这份工程的目录 ：
  • ets/testability/：测试 Ability 与其页面。
  • ets/test/：Hypium 测试用例集合。
  • ets/testrunner/：测试运行器（TestRunner）实现。

ohos/entry/src/ohosTest/ets/testability/TestAbility.ets

• 作用 ：测试入口 UIAbility。
• 你这份工程的关键点 ：
  • onCreate(...) 中通过 AbilityDelegatorRegistry 获取 delegator 与参数。
  • 调用 Hypium.hypiumTest(abilityDelegator, abilityDelegatorArguments, testsuite) 运行测试套件（testsuite 来自 ets/test/List.test.ets）。
  • onWindowStageCreate(...) 加载测试页面 testability/pages/Index。

ohos/entry/src/ohosTest/ets/testability/pages/Index.ets

• 作用：测试 Ability 的简单 UI 页面（显示文本/按钮），方便观察 Ability 是否正常启动与页面渲染。

ohos/entry/src/ohosTest/ets/test/Ability.test.ets

• 作用：一个示例 Hypium 测试用例文件。
• 你这份工程的关键点 ：
  • 使用 describe/it/expect 组织测试并做断言（例如 assertContain / assertEqual）。

ohos/entry/src/ohosTest/ets/test/List.test.ets

• 作用 ：测试套件聚合入口，把多个测试文件组织成一个 testsuite() 导出给 Hypium.hypiumTest(...)。

ohos/entry/src/ohosTest/ets/testrunner/OpenHarmonyTestRunner.ts

• 作用 ：OpenHarmony 的测试运行器实现（实现 @ohos.application.testRunner 的 TestRunner）。
• 你这份工程的关键点 ：
  • onRun() 中通过 AbilityDelegatorRegistry 获取参数。
  • 组装并执行 shell 命令：aa start ... -a TestAbility -b <bundleName> 来启动测试 Ability。
  • 支持 -D 参数控制调试（追加 -D）。

ohos/entry/src/ohosTest/resources/

• 作用：测试模块资源目录。
• 你这份工程的关键点 ：
  • resources/base/profile/test_pages.json：路由列表（包含 testability/pages/Index）。
  • resources/base/element/string.json：module_test_desc、TestAbility_desc、TestAbility_label 等字符串资源。
  • resources/base/element/color.json：启动窗口背景色等颜色资源。

ohos/local.properties

• 作用：本地环境相关配置（通常与本机 SDK 路径等有关）。
• 注意：多为机器相关配置，是否提交取决于项目习惯。

ohos/package.json 与 ohos/package-lock.json

• 作用：Node 生态的包管理文件（某些构建工具链或脚本依赖）。

ohos/node_modules/、ohos/oh_modules/、ohos/build/、ohos/entry/build/

• 作用：依赖缓存与构建产物目录。
• 注意：一般不手改、不提交。

---

你最常改动的文件（建议）

• Flutter 业务/UI ：lib/（尤其 lib/main.dart 或你后续拆分的页面/组件文件）
• Flutter 依赖/资源 ：pubspec.yaml
• Harmony 包名/版本/图标/名称 ：ohos/AppScope/app.json5
• Harmony 构建/Flutter 集成逻辑 ：ohos/hvigorfile.ts、ohos/hvigorconfig.ts

---