Flutter Host — Lab 索引

统一 Flutter 承载工程，所有 Flutter / Dart UI 相关 labs 在此运行。

版本与复现信息

当前已验证版本

项目	版本 / 值
Flutter (FVM 管理)	3.41.10-ohos-1.0.0（OpenHarmony 定制分支）
Dart	3.11.5
Xcode	26.6 (17F113)
macOS	26.6
Android host app 插件模板	Gradle 8.14 / AGP 8.11.1 / Kotlin 2.0.21
支持平台壳	Android / iOS / macOS / ohos（HarmonyOS）

FVM 工作流（必须）

本工程通过 FVM 锁定 Flutter 版本（见 .fvmrc，指向 ohos/3.41.10-ohos-1.0.0， 用于同时支持标准平台与鸿蒙平台）。所有 Flutter 命令一律使用 fvm flutter 前缀， 不要直接使用全局 flutter 命令（全局版本与本工程约束不匹配时会导致依赖解析失败）。

首次进入工程先安装/拉取 FVM 版本：

fvm install   # 按 .fvmrc 安装对应版本
fvm flutter doctor

本机 SDK 路径

通过环境变量或各 host 的 local.properties 配置；勿在文档中写死个人目录。

其他设备复现建议

1. 安装 FVM，进入本目录后执行 fvm install
2. 确保 Dart SDK 与 FVM 内置版本一致（当前 3.11.5）
3. macOS / iOS 侧安装 Xcode 并通过 xcode-select 指向可用版本
4. Android 侧安装 SDK，并在以下任一位置配置：
   • 全局环境：ANDROID_HOME、ANDROID_SDK_ROOT
   • 或 android/local.properties
5. 首次进入工程执行：

cd labs/flutter/host
fvm flutter doctor
fvm flutter pub get

前置条件

• Flutter SDK 在 PATH 中可用（flutter --version）
• Android SDK 已安装；若 shell 环境未自动注入，请确保 android/local.properties 或全局环境能解析 SDK 路径
• 首次运行需网络下载 pub/Gradle 依赖

当前目标

当前先提供最小可运行骨架，用于后续逐步承载：

• Flutter 生命周期
• Flutter 状态管理
• Flutter 路由
• Flutter 后台能力边界
• Flutter ↔ Android / iOS / macOS bridge 调用侧

目录结构

labs/flutter/host/
├── README.md
├── analysis_options.yaml
├── pubspec.yaml
├── lib/
│   ├── main.dart
│   ├── app/
│   │   ├── app.dart
│   │   └── routes/
│   └── topics/
├── test/
├── integration_test/
├── android/                # Flutter Android 宿主壳，用于 MethodChannel / 生命周期映射 / 平台差异实验
├── ios/                    # Flutter iOS 宿主壳
├── macos/                  # Flutter macOS 宿主壳
├── ohos/                   # Flutter 鸿蒙（HarmonyOS）宿主壳
└── topics/
    ├── memory-lifecycle/
    ├── background-tasks/
    └── state-routing-architecture/

设计原则

1. 单一 host：不为每个知识点单独创建完整 Flutter 工程。
2. 保留原生平台壳：
   • android/ 用于 Android 宿主生命周期、MethodChannel、平台差异
   • ios/ 用于 iOS 生命周期与平台桥接
   • macos/ 用于桌面端窗口生命周期与插件/平台能力验证
   • ohos/ 用于鸿蒙（HarmonyOS / OpenHarmony）壳工程与多平台 PlatformChannel 实现
3. 源码与 README 分离但近邻：
   • 源码放 lib/topics/<domain>/<lab-name>/...
   • Lab README 放 topics/<domain>/<lab-name>/README.md
4. docs 直链具体文件：知识库文档必须链接到具体 README 与具体源码文件，不能只链 host 根目录。
5. Flutter 与 Dart 分层：
   • 纯 Dart 运行时实验进入 labs/dart/host
   • Flutter UI / 生命周期 / 路由 / bridge 调用侧进入 labs/flutter/host
6. 先轻后重：首批先放生命周期 / 状态管理 / 路由；后台任务与 bridge 先做边界演示，再逐步补复杂集成。

初始化验证命令

cd labs/flutter/host
fvm flutter pub get
fvm flutter analyze
fvm flutter test

注意：fvm flutter test 只会执行 test/ 下的 widget 测试； integration_test/ 下的端到端集成测试需要真机 / 模拟器，运行方式见 integration_test/README.md。

如需平台壳验证：

fvm flutter devices          # 查看可用设备（含 ohos 设备）
fvm flutter run -d macos
fvm flutter run -d ios
fvm flutter run -d android
fvm flutter run -d <ohos-device-id>   # 鸿蒙设备，先通过 devices 获取 id

对应文档

• Flutter 生命周期：docs/02-memory-lifecycle/03-flutter-lifecycle-overview.md
• Flutter 后台边界：docs/03-background-tasks/02-flutter-background-boundary.md
• Flutter 状态管理：docs/04-state-routing-architecture/02-riverpod-provider-bloc-getx.md
• Flutter 路由：docs/04-state-routing-architecture/03-flutter-routing-go-router-navigator.md