Flutter Host — Lab 索引

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

版本与复现信息

当前已验证版本

项目	版本 / 值
Flutter	3.22.3
Dart	3.4.4
Xcode	26.6 (17F113)
macOS	26.6
Android host app 插件模板	Flutter create 默认 Android 宿主（AGP 7.3.0 / Kotlin 1.7.10）
支持平台壳	Android / iOS / macOS

本机 SDK 路径

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

其他设备复现建议

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

cd labs/flutter/host
flutter doctor
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 宿主壳
└── topics/
    ├── memory-lifecycle/
    ├── background-tasks/
    └── state-routing-architecture/

设计原则

1. 单一 host：不为每个知识点单独创建完整 Flutter 工程。
2. 保留原生平台壳：
   • android/ 用于 Android 宿主生命周期、MethodChannel、平台差异
   • ios/ 用于 iOS 生命周期与平台桥接
   • macos/ 用于桌面端窗口生命周期与插件/平台能力验证
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
flutter pub get
flutter analyze
flutter test

如需平台壳验证：

flutter run -d macos
flutter run -d ios
flutter run -d android

对应文档

• 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