第2章创建Flutter Module

2、创建Flutter Module：使用命令行和Android Studio创建Flutter Module项目，理解Module与App项目的区别

好，咱们正式开始动手了。

这一节的核心任务很简单——创建一个Flutter Module。但你别小看这一步，很多人在一开始就栽了跟头。我见过不少团队，Module创建出来跑不起来，最后发现是目录结构搞错了，或者跟主工程版本对不上。

所以这一节，我会带你走两条路：一条是命令行，一条是Android Studio。两条路都能到罗马，但路上风景不一样。

2.1 什么是Flutter Module？

先搞清楚概念。

Flutter App项目，你肯定熟悉。你执行 flutter create my_app，得到一个完整的、能独立运行的应用。它有 lib/main.dart，有 android/ 和 ios/ 目录，能直接打包成APK或IPA。

但Flutter Module不一样。它不是一个完整的应用，而是一个「可嵌入的组件」。说白了，它没有自己的 main() 入口，也不能独立运行。它的存在，就是为了被原生Android或iOS项目引用。

核心区别一句话：

App项目：独立运行，有入口，有完整生命周期。
Module项目：寄生运行，无入口，依赖原生宿主。

嗯，这里要注意：Module项目虽然不能独立运行，但你可以用 flutter run 调试它——前提是你得指定一个宿主应用。这个我们后面会讲。

2.2 方法一：命令行创建（我推荐的方式）

我个人习惯用命令行。为什么？因为干净、可控、不会有多余的IDE缓存。

打开终端，进入你的工作目录，执行：

flutter create --template module my_flutter_module

就这么一行。我们来拆解一下：

--template module：告诉Flutter，我要创建的是Module，不是App。
my_flutter_module：项目名称。你可以改成你想要的，比如 flutter_share_module 或 payment_module。

执行完后，你会看到类似这样的输出：

Creating project my_flutter_module...
  my_flutter_module/.android/
  my_flutter_module/.ios/
  my_flutter_module/lib/
  my_flutter_module/test/
  my_flutter_module/pubspec.yaml
  my_flutter_module/example/
  ...

注意看，这里多了 .android/ 和 .ios/ 目录。这两个目录是隐藏的，前面带点。它们就是Flutter Module的「原生壳」——用于编译和调试，但不会被提交到你的主工程里。

小技巧：

如果你用Git管理项目，记得把 .android/ 和 .ios/ 加到 .gitignore 里。这两个目录每次 flutter pub get 都可能重新生成，没必要提交。

2.3 方法二：Android Studio创建（可视化操作）

如果你更习惯IDE，Android Studio也支持。不过说实话，我很少用这个方式，因为有时候版本不对会踩坑。

步骤很简单：

打开Android Studio，选择 File → New → New Flutter Project。
在对话框里，选择 Flutter Module 类型。
填写项目名称和路径，点击 Finish。

嗯，这里有个坑。Android Studio创建Module时，默认会帮你生成一个 example/ 目录。这个目录里是一个完整的Flutter App，用来单独调试你的Module。我个人觉得这个设计挺贴心的，但如果你不需要，可以删掉它。

注意：

Android Studio创建的Module，有时候会因为Flutter插件版本问题，导致 .android/ 目录的Gradle版本跟你的主工程不一致。我曾经因为这个折腾了一下午——主工程用AGP 7.0，Module生成的是AGP 4.2，编译直接报错。

解决办法：手动修改 .android/ 目录下的 build.gradle 和 gradle-wrapper.properties，保持跟主工程一致。

2.4 Module项目的目录结构解析

创建完成后，我们来看看Module长什么样。我画了一张图，帮你快速理解：

这张图你看懂了吗？核心就三点：

lib/：你的Dart代码放这里。没有 main.dart 入口，取而代之的是你自定义的Widget。
.android/：这是Flutter自动生成的Android壳项目。它包含一个 FlutterPlugin 注册类，用于跟原生通信。
pubspec.yaml：跟App项目一样，管理依赖。但注意，Module的 pubspec.yaml 里没有 flutter: 下的 module: 字段——这个字段是App项目才有的。

2.5 Module与App项目的关键区别

我整理了一个表格，方便你对比：

对比项	Flutter App	Flutter Module
入口文件	`lib/main.dart` 含 `runApp()`	无 `main.dart`，或只有Widget定义
独立运行	可以	不可以（需宿主）
原生目录	`android/`、`ios/`（可见）	`.android/`、`.ios/`（隐藏）
构建产物	APK / IPA	AAR / Framework
使用场景	独立应用	嵌入原生项目
调试方式	`flutter run`	`flutter run` + 宿主配置

你看，区别还是挺明显的。尤其是「构建产物」这一行——Module最终会编译成AAR（Android）或Framework（iOS），然后被原生项目引用。这个我们后面会详细讲。

2.6 避坑指南：我踩过的三个坑

最后，分享几个我实际项目中遇到的坑，你提前知道，能省不少时间。

坑一：Module名称不要用下划线

我曾经创建了一个 flutter_payment_module，结果在Android Studio里引用时，Gradle报错说找不到模块。查了半天，发现是下划线导致路径解析出问题。后来改成 flutterPaymentModule 就好了。

建议：Module名称用驼峰命名，或者干脆全小写无分隔符。

坑二：Flutter版本必须跟主工程对齐

这个坑我踩过两次。主工程用Flutter 3.7，Module用3.10，编译时Flutter引擎版本不一致，直接崩溃。解决办法：在Module的 pubspec.yaml 里指定 environment: 的Flutter版本范围，比如 ">=3.7.0 <4.0.0"。

坑三：.android/ 目录不要手动修改

有次我手贱，改了 .android/ 下的 settings.gradle，结果下次 flutter pub get 直接覆盖了我的修改。记住，这个目录是自动生成的，任何手动修改都会被重置。如果你需要自定义Gradle配置，应该通过 android/gradle.properties 或主工程的配置来传递。

好了，这一节的内容就到这里。你现在应该能熟练创建Flutter Module，并且知道它跟App项目的本质区别了。下一节，我们会把这个Module真正嵌入到Android项目里——那才是重头戏。

公众号:蓝海资料掘金营，微信deep3321