本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

Flutter Module 的特点：

• 没有 main.dart 入口文件

• 不能通过 flutter run 直接运行

• 必须集成到原生宿主应用中运行

• 支持热重载/热重启开发体验

二、三种运行方案

2.1 方案一：使用 Example 项目（官方推荐）

原理：创建 Module 时自动生成 example/ 目录，这是一个完整的 Flutter App，用于演示和调试 Module。

适用场景：

• 模块开发阶段

• 功能自测

• UI 效果预览

操作步骤：

# 1. 创建 Module
flutter create -t module my_flutter_module

# 2. 进入 Module 目录
cd my_flutter_module

# 3. 查看目录结构
ls -la
# 输出示例：
# .android/     # 自动生成的 Android 宿主（不手动修改）
# .ios/         # 自动生成的 iOS 宿主（不手动修改）
# example/      # 完整可运行的示例应用 ← 用于调试
# lib/          # 模块代码
# pubspec.yaml  # 依赖配置

# 4. 进入 example 目录
cd example

# 5. 运行示例应用
flutter run
# 或指定设备运行
flutter run -d chrome        # Web 预览
flutter run -d windows       # Windows 桌面预览
flutter run -d macos         # macOS 桌面预览

example 项目特点：

• 完整的 Flutter App：包含 main.dart 入口

• 自动依赖：自动引入上级目录的 Module

• 独立运行：可独立打包发布

• 热重载支持：修改 Module 代码，example 实时生效

pubspec.yaml 自动配置：

name: example
description: Demonstrates how to use the my_flutter_module plugin.

dependencies:
  flutter:
    sdk: flutter
  my_flutter_module:
    path: ../  # 自动引用上级目录的 Module

example 目录：

example/
├── lib/
│   └── main.dart        # 演示入口，调用 Module 功能
├── android/             # 独立 Android 应用
├── ios/                 # 独立 iOS 应用
├── web/                 # 独立 Web 应用
└── pubspec.yaml         # 依赖配置

2.2 方案二：使用宿主应用调试（混合开发场景）

原理：Module 的真正运行环境是原生宿主应用，通过原生 IDE 运行宿主，Flutter 代码热重载。

适用场景：

• 集成测试

• 原生与 Flutter 交互调试

• 真实环境验证

2.2.1 Android 宿主调试

# 1. 创建 Android 原生项目（或使用现有项目）
# Android Studio → New Project

# 2. 在 Android 项目中引入 Flutter Module
# settings.gradle
setBinding(new Binding([gradle: this]))
evaluate(new File(
  settingsDir.parentFile,
  'my_flutter_module/.android/include_flutter.groovy'
))

include ':my_flutter_module'
project(':my_flutter_module').projectDir = new File('../my_flutter_module')

运行方式：

# 方式 A：Android Studio 运行
# 1. 打开 Android 宿主项目
# 2. 点击 Run 按钮（▶）
# 3. Flutter Module 代码修改后，点击 ⚡ 热重载

# 方式 B：命令行运行（需配置 Gradle）
cd android_host_app
./gradlew installDebug
adb shell am start -n com.example.host/.MainActivity

2.2.2 iOS 宿主调试

# 1. 创建 iOS 原生项目
# Xcode → New Project

# 2. 在 Podfile 中引入 Flutter Module
# Podfile
flutter_application_path = '../my_flutter_module'
load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')

target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end

运行方式：

# 方式 A：Xcode 运行
# 1. 打开 .xcworkspace
# 2. 点击 Run 按钮（▶）
# 3. Flutter Module 代码修改后，点击 ⚡ 热重载

# 方式 B：命令行运行
cd ios_host_app
pod install
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp

宿主调试特点：

• 真实环境：完整的原生应用上下文

• 交互测试：可测试 MethodChannel 通信

• 性能分析：真实设备性能数据

• 配置复杂：需要原生开发环境配置

2.3 方案三：使用 Flutter 工具的 Module 调试模式

原理：Flutter 提供了专门针对 Module 的调试命令，可临时启动一个宿主应用。

适用场景：

• 快速验证

• 无需原生开发的场景

• 纯 Dart 代码调试

# 1. 进入 Module 根目录
cd my_flutter_module

# 2. 启动 Module 调试模式
flutter run -d <device_id>

# 实际运行效果：
# - 自动编译 Module
# - 启动临时宿主应用
# - 加载 Module 中的首个 Widget
# - 支持热重载

限制说明：

• 只能预览 Module 默认入口

• 无法测试原生交互

• 宿主环境非真实项目配置

适用设备：

# Web 预览（最快速）
flutter run -d chrome

# 桌面预览
flutter run -d windows
flutter run -d macos
flutter run -d linux

# 移动设备预览
flutter run -d android
flutter run -d ios

三、三种方案对比

对比维度	Example 项目	宿主应用	Module 调试模式
配置复杂度	⭐ 极低	⭐⭐⭐⭐⭐ 高	⭐⭐ 低
真实度	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 真实	⭐⭐ 较低
原生交互测试	不支持	支持	不支持
热重载支持	支持	支持	支持
启动速度	快	慢	快
依赖环境	Flutter 仅	Flutter + 原生 SDK	Flutter 仅
推荐场景	日常开发	集成测试	快速验证

四、操作示例

4.1 场景一：新 Module 开发，快速看 UI 效果

# 1. 创建 Module
flutter create -t module my_login_module
cd my_login_module

# 2. 编写模块代码
# lib/login_screen.dart
import 'package:flutter/material.dart';

class LoginScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('登录模块')),
      body: Center(
        child: ElevatedButton(
          child: Text('登录'),
          onPressed: () {},
        ),
      ),
    );
  }
}

# 3. 在 example 中引用
# example/lib/main.dart
import 'package:flutter/material.dart';
import 'package:my_login_module/login_screen.dart';

void main() {
  runApp(MaterialApp(
    home: LoginScreen(),
  ));
}

# 4. 运行 example
cd example
flutter run -d chrome  # Web 实时预览

4.2 场景二：模块集成测试，验证原生交互

# 1. 已有原生项目，需要集成 Module
# 项目结构：
# /Users/me/projects/
#   ├── android_host_app/    # 原生 Android 应用
#   └── my_flutter_module/   # Flutter 模块

# 2. 在 Android 宿主中配置
cd android_host_app

# 3. 运行 Android 宿主
# Android Studio 打开项目
# 点击 Run 按钮

# 4. Flutter Module 代码修改
cd ../my_flutter_module
# 修改 lib/ 下的代码
# 在 Android Studio 中点击 ⚡ 热重载
# 宿主应用即时更新

4.3 场景三：快速验证模块逻辑

# 1. 进入 Module 目录
cd my_flutter_module

# 2. 确保模块有默认导出
# lib/my_flutter_module.dart
export 'src/my_widget.dart';

# 3. 快速运行预览
flutter run -d chrome

# 4. 查看效果
# Chrome 自动打开，显示模块默认 Widget

如果创建 Module 后没有 example 目录？

较新版本的 Flutter 默认生成 example 目录。如果没有，可以手动创建：

# 方法1：使用 --template=module 重新创建
flutter create -t module --org com.example my_new_module

# 方法2：手动创建 example 目录
cd my_module
mkdir example
cd example
flutter create .
# 修改 pubspec.yaml 添加 path 依赖