3、创建Flutter Module项目：命令行创建与项目结构全解析

好，咱们直接进入正题。这一章我带你亲手创建一个Flutter Module，然后把它里里外外拆开看一遍。说实话，很多同学在集成时遇到坑，都是因为对Module的项目结构理解不够深。咱们今天就把它彻底搞明白。

3.1 使用命令行创建Flutter Module

创建Module的方式其实很简单，但我建议你直接用命令行，别用IDE的图形界面。为什么？因为命令行最干净，不会生成一些IDE自己加进去的乱七八糟的东西。我在项目中吃过这个亏——用Android Studio创建Module，结果多了一堆.gradle缓存文件，排查了半天才发现是IDE搞的鬼。

打开终端，执行下面这条命令：

flutter create --template module my_flutter_module

这里解释一下参数：

  • --template module：指定创建的是Flutter Module，不是普通应用
  • my_flutter_module：模块名称，你可以改成自己的项目名

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

Creating project my_flutter_module...
  my_flutter_module/.gitignore
  my_flutter_module/.metadata
  my_flutter_module/pubspec.yaml
  my_flutter_module/README.md
  my_flutter_module/lib/main.dart
  my_flutter_module/test/widget_test.dart
  my_flutter_module/example/
  my_flutter_module/android/
  my_flutter_module/ios/
  my_flutter_module/linux/
  my_flutter_module/macos/
  my_flutter_module/windows/
  my_flutter_module/web/
Running "flutter pub get" in my_flutter_module...      2.3s
小提示：创建完成后，Flutter会自动执行flutter pub get。如果网络不好卡住了，可以手动进目录再跑一次。

3.2 Module项目结构解析

创建完了，咱们看看这个Module长什么样。我直接画个图，你一眼就能看明白：

my_flutter_module/ lib/ (Dart源码) android/ (原生壳) ios/ (原生壳) pubspec.yaml main.dart (入口) flutter_module.gradle Podfile src/ (业务代码) .android/ (隐藏) 📌 关键文件说明： • pubspec.yaml — 模块的"身份证"，声明依赖、版本、配置 • lib/main.dart — Flutter代码入口，暴露给原生调用的组件 • android/flutter_module.gradle — Android集成的桥梁文件 • .android/ — 运行flutter build时自动生成，不要手动修改

嗯，这张图基本把Module的骨架画清楚了。我重点说几个容易忽略的点：

  • lib/目录：这是你写Flutter业务代码的地方。注意，main.dart不是传统意义上的应用入口，而是Module的暴露入口。你想想看，原生App调用Flutter页面时，实际上就是通过这个文件里的Widget来启动的。
  • android/目录：这是一个"壳工程"，里面只有一个flutter_module.gradle文件。它存在的意义是告诉Android Gradle插件：嘿，这里有个Flutter Module要集成进来。
  • .android/目录：这个目录默认是隐藏的。当你执行flutter build apk或者flutter run时，Flutter工具链会自动生成它。我曾经手贱改过里面的代码，结果下次构建全被覆盖了——白忙活一场。

3.3 pubspec.yaml配置详解

pubspec.yaml是Flutter项目的"命根子"。我每次接手新项目，第一件事就是打开这个文件看看。它长这样：

name: my_flutter_module
description: "A Flutter module for Android integration"
version: 1.0.0

environment:
  sdk: ">=3.0.0 <4.0.0"

dependencies:
  flutter:
    sdk: flutter
  # 这里加你的业务依赖
  cupertino_icons: ^1.0.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^2.0.0

flutter:
  uses-material-design: true
  # 模块的导出配置
  module:
    androidX: true
    androidPackage: com.example.my_flutter_module
    iosBundleIdentifier: com.example.myFlutterModule

咱们一行行拆开看：

配置项 说明 我的建议
name 模块名称，也是Dart包名 用下划线命名法，别用驼峰
environment.sdk Dart SDK版本约束 建议写>=3.0.0，兼容性好
module.androidX 是否启用AndroidX 必须true，现在没人用support库了
module.androidPackage Android端的包名 和你的原生项目包名保持一致
⚠️ 避坑指南：我曾经遇到过一个坑——androidPackage写错了包名，结果Flutter和Android两边资源ID冲突，编译报错"attribute already defined"。排查了整整一下午才发现是这里的问题。所以，创建Module时就把包名写对，后面能省很多事。

另外，flutter:下面的module:配置块是Module特有的。普通Flutter应用没有这个配置。它定义了Module如何暴露给原生端。说白了，原生App就是通过这个配置找到Flutter的入口的。

3.4 Android原生项目结构

最后咱们看看Android那边。当你把Flutter Module集成到Android项目后，原生项目里会多出一些东西：

你的Android项目/
├── app/
│   ├── src/
│   │   └── main/
│   │       ├── java/          # 你的原生代码
│   │       └── res/           # 原生资源
│   └── build.gradle           # 这里要加Flutter依赖
├── settings.gradle            # 这里要include Flutter Module
└── my_flutter_module/         # 这就是你刚才创建的Module
    ├── lib/
    ├── android/
    └── pubspec.yaml

这里有两个关键文件需要修改：

1. settings.gradle：在文件末尾加上：

setBinding(new Binding([gradle: this]))
evaluate(new File(
    settingsDir.parentFile,
    'my_flutter_module/.android/include_flutter.groovy'
))

2. app/build.gradle：在dependencies块里加上：

implementation project(':flutter')

嗯，这两步做完，Android项目就能"看到"Flutter Module了。我刚开始做集成时，总是忘记改settings.gradle，结果编译报错说找不到':flutter'这个模块。你想想看，原生项目都不知道Flutter Module在哪，怎么可能编译通过呢？

核心要点：Flutter Module的集成本质上是把Flutter的Dart代码编译成原生库（AAR或Framework），然后让原生项目引用。所以，settings.gradle和build.gradle的配置就是告诉Gradle：嘿，这里有个Flutter模块，帮我编译并链接进来。

好了，这一章的内容就到这里。你跟着命令行创建一遍，再对照着项目结构图看一遍，应该就能把Flutter Module的骨架摸清楚了。下一章咱们会真正开始写集成代码，到时候这些结构知识都会用上。

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

← 上一章 📖 返回目录 下一章 →