Flutter .new：一个命令行与Web双入口的项目脚手架生成系统

前一阵我在帮团队整理工程初始化流程的时候，脑子里一直冒出一个念头：为什么新建一个 Flutter 项目这件事，总是要开命令行、敲一串参数、等依赖拉取，然后再手工补一堆团队规范？对比一下我们在网页上新建文档的体验，在地址栏输入一个 .new 形式的快捷入口，回车就能进入创建流程，那种“输入即开始”的感觉比翻菜单找按钮爽太多了。顺着这个思路，我折腾出了一个小工具，取名 Flutter .new。本质上，它是围绕 Flutter 项目初始化做的一套脚手架生成系统，同时提供命令行和浏览器两种入口，你只要填上项目名、选几个选项，它就能吐出一套可直接运行的 Flutter 工程。这篇文章会把我的设计思路、技术选型、完整实现过程和踩坑记录都摊开来讲，适合正在做 Flutter 工程化建设、或者想提升团队新项目起手速度的开发者参考。

1. 项目形态与思路拆解

1.1 ".new"模式的启发与定位

".new" 不是某个产品的专利，而是一种交互范式：很多在线文档服务在地址栏提供特定后缀，输入后直接进入新建页面，把“创建”这个动作从应用内部的按钮变成了入口层操作。Flutter 项目初始化虽然发生在本地命令行，但完全可以借鉴同样的心智模型。用户不需要知道 flutter create 有哪些参数，不需要记得要先建目录还是先加依赖，只需要告诉工具“我要一个叫 xxx 的项目”，剩下的事全部交给工具。

所以 Flutter .new 的定位不是替代官方 flutter create 命令，而是在它之上叠加一层“业务化”的封装。官方命令解决的是“生成一个能跑起来的空壳”，Flutter .new 解决的是“生成一个符合团队规范、带好状态管理方案、路由方案、代码分析规则、甚至带好 Git 初始化的工程模板”。这两者不冲突，前者是底座，后者是把底座打磨成产线。

项目最终形态包含两部分：一个名为 flutter_new 的 CLI 工具，以及一个用 Flutter Web 做的可视化页面。CLI 面向习惯命令行的开发者，Web 页面面向想快速看一眼模板结构、或者团队里不太熟悉命令行的新人。两条入口共用同一套模板渲染和生成逻辑，只是输入方式和产物交付方式不同。这个设计我在后文会展开讲。

1.2 为什么不用 flutter create 硬扛

有人会问，直接写个脚本封装 flutter create 不行吗？当然可以，但实际用下来会发现几个问题。

第一，flutter create 生成的模板是官方通用结构，它不会替你考虑“团队用 getX 还是 bloc”“路由统一用 go_router 还是自带 Navigator”“需不需要默认加国际化文件”“analysis_options 要不要用更严格的规则”。这些差异如果靠每次创建后再手工调整，效率低不说，还很容易漏掉某个细节。

第二，flutter create 的参数是固定的，它不支持自定义扩展。你没法通过 flutter create --with-bloc 这种参数让它生成 bloc 模板，因为这不是官方的职责范围。而 Flutter .new 的核心价值恰恰是“可扩展的模板体系”，团队标准变了，只需要改模板内容，不用改生成器代码。

第三，团队规范和工具链是持续演进的。某个新项目可能需要额外接入日志组件、网络层封装、主题配置，这些内容如果散落在每个开发者的记忆里，就会有人忘记。把规范固化进模板，是工程化里性价比很高的一件事。

我用一张表说明 Flutter .new 与 flutter create 的差异：

1.3 核心设计原则：配置驱动、模板封装

在动手写代码前，我给自己定了几条设计原则，后来发现这几条原则直接决定了这个工具能不能被团队长期使用。

原则一：生成器不写死项目结构。所有要生成的文件都放在 templates 目录里，用一个 manifest.json 描述“哪些文件要输出、输出到什么位置、在什么条件下输出”。生成器只负责解释清单，不懂也不关心业务细节。这样带来的好处非常直接：模板逻辑和代码逻辑彻底分离，换一套模板就等于换一个工具。

原则二：所有可变量集中收敛。项目名、组织名、状态管理方案、路由方案、是否启用某个 feature，全部收敛到一个配置对象里。模板渲染时只从这个对象取数据，避免散落一堆全局变量。这个对象本质上是用户问答结果的映射。

原则三：生成结果必须具备即时可运行性。模板里所有代码都要过一遍 flutter analyze，不允许生成一个带着语法错误、一打开就飘红的项目。要做到这一点，模板本身就必须长期维护，每次改完模板都要实际生成一次并跑检查。

2. 核心功能拆解与关键技术点

2.1 交互式问答：把需求翻译成模板变量

CLI 端的交互设计参考了现代脚手架工具的“问答式向导”。工具启动后逐题提问，每题给出编号选项，用户输入编号或直接回车选默认值。问完一组问题，工具就收集到了完整的配置信息。

我实际设计的问题大概是这个流程：

1. 请输入项目名（必填，需要符合 Dart 包命名规范）；
2. 请输入组织名（用于 Android 包名和 iOS bundle id，默认 com.example）；
3. 选择状态管理方案：无 / Provider / Riverpod / Bloc；
4. 是否启用 go_router 路由？（可选）；
5. 是否生成样板测试文件？（默认生成）；
6. 是否自动执行 flutter pub get？（默认执行）。

每个回答都会被写入一个 Config 对象。比如用户选择了 Bloc，Config 里 stateMgmt = bloc，这个字段随后会驱动两层变化：一层是 pubspec.yaml 里要加入 bloc 和 flutter_bloc 依赖，另一层是 lib 目录里要生成 feature 样板代码。

Web 端做的是同一件事，只是把命令行问题换成了表单控件。前端收集选项后，将同样的 Config 结构 POST 给服务端，由服务端调用生成核心。两条入口最终汇合到同一个 generate() 方法，这是我刻意保住的架构一致性，避免两套逻辑分别维护。

2.2 模板渲染：用 mustache 而不是字符串替换

模板渲染是最容易想简单、实际做起来又最需要谨慎的一环。如果你拿到模板文件后直接做 String.replaceAll，把项目名替换进去，第一版确实能跑，但只要模板里出现几十个变量，或者出现“只有选择 Bloc 才生成某段代码”的条件逻辑，字符串替换就会失控。

这里我选了 Dart 生态里比较成熟的 mustache_template 包。mustache 是极简的模板语言，核心语法只有三种：{{variable}} 做变量插值，{{#section}}...{{/section}} 做条件区域，{{{variable}}} 做不转义插值。这三种能力刚好覆盖脚手架模板的绝大多数需求。

核心渲染代码是这样的：

import 'package:mustache_template/mustache_template.dart'; String renderTemplate(String source, Map<String, Object> context) { final template = Template(source, name: 'inline'); return template.renderString(context); }

实际用的时候，我会把 Config 对象先转成 Map，再传给 renderString。模板里的变量名必须和 Config 字段严格对应，这个约束靠 manifest 里的 variables 字段声明来保证。

有一个细节值得注意：mustache 默认界定符是双花括号，而 Dart 的字符串插值用的是 ${}，两者在大多数场景不冲突。但在一些特殊的模板文件里，比如要生成一份包含 mustache 语法教学片段的文档，或者某些代码里真的需要保留双花括号字面量，就会发生误渲染。解决方案是给模板文件做标记，遇到这类文件直接按原始内容拷贝，不走渲染逻辑；另一种方案是使用 mustache 的界定符切换语法，把双花括号临时替换成其他符号。

2.3 自动命令编排：生成不等于结束

模板文件写磁盘只是第一步，一个能跑的项目还需要依赖。CLI 在生成完所有文件后会自动执行 flutter pub get，并把命令输出实时流到终端。这里不建议用 Process.run 这种方式，因为 pub get 可能跑十几秒，阻塞式等待会让工具看起来像卡死了。

我用的是 Process.start，把 stdout 和 stderr 通过管道转接到当前终端：

import 'dart:io'; Future<int> runPubGet(String workingDirectory, {void Function(String line)? onLog}) async { final process = await Process.start( 'flutter', ['pub', 'get'], workingDirectory: workingDirectory, ); process.stdout.listen((byte) { stdout.add(byte); if (onLog != null) onLog(byte.toString()); }); process.stderr.listen((byte) { stderr.add(byte); }); return process.exitCode; }

这里有几个容易踩的坑：workingDirectory 必须指向生成目录，不能是工具所在目录；命令要在所有模板文件写完后再执行，否则依赖清单不完整会直接失败；执行失败后不要立刻退出，先把错误信息完整打印出来，提示用户手动在生成目录里执行 flutter pub get 排查。

git init 是另一个可选动作。我倾向于默认执行，但允许用户用 --no-git 跳过。git init 很快，只是要不要执行取决于团队习惯，有些公司会把 Git 仓库创建放在内网流水线上，不在本地处理。

2.4 Web 端的"输入即生成"链路

Web 端的技术方案我前后调整过两版。第一版想让浏览器直接调用本地的通用代码，通过在线服务生成，前端只需要填表单然后下载 zip。第二版更简洁：前端只负责收集配置和展示下载结果，模板文件放在服务端，后端复用与 CLI 完全相同的生成核心。

后端我用的是 shelf，这是 Dart 生态里比较轻量的 HTTP 服务框架。核心接口只有一个 POST /api/generate，接收 JSON 格式的配置，返回 ZIP 文件流。

这个链路的关键在于“复用”。生成核心本身不关心文件最终写到磁盘还是打包进内存，它只负责根据配置产出文件清单和字节内容。CLI 场景下，这些字节被写到临时目录；Web 场景下，这些字节被塞进 archive 包打包。我把这个思路抽成了两个层次：核心生成层负责“产出内容”，适配层负责“搬运产物”。

代码上大概是这样的结构：

Future<List<GeneratedFile>> buildProject(ProjectConfig config) async { final files = <GeneratedFile>[]; // 遍历 manifest，渲染模板，收集文件字节 return files; } // CLI 适配 for (final file in await buildProject(config)) { File('${outputDir}/${file.path}').writeAsBytesSync(file.bytes); } // Web 适配 final archive = Archive(); for (final file in await buildProject(config)) { archive.addFile(ArchiveFile(file.path, file.bytes.length, file.bytes)); }

打包用 archive 包，注意把 Content-Type 设置为 application/zip，加上 Content-Disposition 附件头，浏览器才会正确触发下载而不是把乱码显示在页面上。服务端每次生成完要清理临时目录，防止磁盘被重复生成撑爆。

3. 从零搭建 Flutter .new 的实操记录

3.1 初始化 CLI 工程与目录规划

工具本身用 Dart 写，因为这样可以和 Flutter 生态无缝衔接，不需要引入第二门语言。先用 Dart 官方的命令行模板初始化：

dart create -t console flutter_new

初始化后我按职责把目录整理成下面这样：

flutter_new/ ├── bin/ │ └── flutter_new.dart # 入口，只做参数解析 ├── lib/ │ ├── config.dart # ProjectConfig 模型 │ ├── questions.dart # CLI 问答逻辑 │ ├── generator.dart # 生成核心 │ └── packer.dart # 打包逻辑（Web 复用） ├── templates/ │ ├── core/ # 基础模板文件 │ ├── feature_bloc/ # Bloc 功能模块模板 │ ├── feature_riverpod/ # Riverpod 功能模块模板 │ └── manifest.json # 模板清单 └── web/ └── lib/ ├── main.dart # Flutter Web 前端 └── api.dart # 调用后端接口

bin 入口要做得足够薄，只负责解析参数然后调用 lib 下的 run 方法。真正的业务逻辑全部放在 lib，这样可以保证 CLI 和维护工具能复用同一套代码，也方便写单元测试。

3.2 设计模板清单 manifest

manifest.json 是整个工具的“路由表”，生成器靠它才知道哪个文件该放到哪里。我先定义一批基础变量，然后再定义文件清单。

一个简化版的 manifest 是这样的：

{ "variables": [ "projectName", "org", "stateMgmt", "useRouter" ], "files": [ { "source": "core/pubspec.yaml", "output": "pubspec.yaml" }, { "source": "core/analysis_options.yaml", "output": "analysis_options.yaml" }, { "source": "core/lib/main.dart", "output": "lib/main.dart" }, { "source": "core/lib/app.dart", "output": "lib/app.dart" }, { "source": "feature_bloc/lib/feature/feature_page.dart", "output": "lib/feature/feature_page.dart", "condition": "stateMgmt == 'bloc'" }, { "source": "feature_riverpod/lib/feature/feature_page.dart", "output": "lib/feature/feature_page.dart", "condition": "stateMgmt == 'riverpod'" } ] }

这里 condition 字段是字符串表达式，生成器拿到后用简单的求值判断是否产生这个文件。条件表达式支持 ==、!=、&& 这几个操作符，够用但不追求完备。variables 字段声明了所有模板中可能出现的变量名，生成器在渲染前会检查 Config 是否完整覆盖，缺字段时直接抛错，而不是等到模板渲染出来一堆空字符串才发现问题。

模板里的 pubspec.yaml 会写成 mustache 格式：

name: {{projectName}} description: A new Flutter project. dependencies: flutter: sdk: flutter {{#stateMgmt == 'bloc'}} flutter_bloc: ^8.1.0 {{/stateMgmt == 'bloc'}} {{#stateMgmt == 'riverpod'}} flutter_riverpod: ^2.3.0 {{/stateMgmt == 'riverpod'}}

mustache 的条件区域第一眼可能不太习惯，但它比用字符串拼接依赖列表要清晰得多，每个依赖都待在它所属的状态管理方案区块里。

3.3 编写核心生成逻辑与条件渲染

生成器的核心是一个遍历 manifest 然后按规则处理文件的循环。我把最核心的生成逻辑写在这里，供大家参考：

class ProjectGenerator { final String templateRoot; final ProjectConfig config; ProjectGenerator({required this.templateRoot, required this.config}); List<GeneratedFile> build() { final manifest = loadManifest(); final files = <GeneratedFile>[]; for (final item in manifest.files) { if (item.condition != null && !evaluateCondition(item.condition!)) { continue; } final sourcePath = '$templateRoot/${item.source}'; final sourceBytes = File(sourcePath).readAsBytesSync(); List<int> outputBytes; if (isTemplateFile(sourcePath)) { final sourceText = utf8.decode(sourceBytes); final rendered = renderTemplate(sourceText, config.toMap()); outputBytes = utf8.encode(rendered); } else { outputBytes = sourceBytes; } files.add(GeneratedFile(item.output, outputBytes)); } return files; } }

isTemplateFile 的判断逻辑是：扩展名属于 .dart、.yaml、.md、.json、.xml 这类文本文件的，都走渲染；图片、字体、gradle wrapper jar 包这类二进制文件，直接字节拷贝。这个区分很重要，如果对二进制内容做 mustache 渲染，大概率会把文件搞损坏。

生成结束后还有一道自检工序：检查关键文件是否都存在，比如 pubspec.yaml、lib/main.dart、analysis_options.yaml。如果缺少任何一项，工具直接报错退出，并提示用户检查 manifest 配置。这种“自我检查”虽然简单，但在模板调整频繁的初期阶段能拦住不少低级失误。

3.4 本地全局安装与命令发布

开发调试阶段，最方便的是用 Dart 的全局激活功能：

dart pub global activate --source path .

激活后，bin 目录下定义的可执行命令就会被挂到全局，直接在任意目录运行 flutter_new 就能测试。开发期间每次改了代码，执行一次 activate 刷新即可。

发布给团队使用时，有几个选项。最省事的是把工具上传到公共包仓库，这样团队成员一行命令就能安装。但考虑到很多团队更希望模板仓库和生成器分开维护，我的建议是生成器做通用化，模板放独立 Git 仓库，工具启动时拉取模板分支。这样生成器很少需要升级，模板却能持续迭代。

交叉编译也是值得考虑的方向。dart compile exe 可以把工具编译成单文件可执行程序，不依赖 Dart SDK 环境，适合放在内网共享目录里直接下载。不过要注意，编译出的二进制仍然需要在机器上能找到 Flutter SDK，因为它内部调用的 flutter 命令基于 SDK，这一点在项目文档里要写清楚。

3.5 完整生成一次项目的实测走读

我用一个实际命令演示完整的生成流程：

flutter_new demo_app --org com.example --state bloc --router go_router --with-test

命令执行后，终端会显示这样的输出：

正在读取模板清单... 加载到 18 个模板文件 生成 lib/main.dart ... 生成 lib/app.dart ... 生成 pubspec.yaml ... 跳过 feature_riverpod 相关文件 执行 flutter pub get ... 正在同步依赖，请稍候... Done! 项目已生成到 ./demo_app

生成完成后，进入 demo_app 目录看结构：

demo_app/ ├── android/ ├── ios/ ├── lib/ │ ├── main.dart │ ├── app.dart │ ├── feature/ │ │ ├── feature_page.dart │ │ └── widget/counter_card.dart │ └── core/ │ ├── routes/app_router.dart │ └── theme/app_theme.dart ├── test/ │ └── widget_test.dart ├── pubspec.yaml └── analysis_options.yaml

关键文件已经不再是官方默认模板，而是带有业务分层结构的工程。pubspec.yaml 里自动加了 flutter_bloc、go_router、flutter_lints 等依赖，main.dart 里初始化了路由表并挂载了主题。生成完的工程可以直接跑测试和静态检查，不需要再补任何东西。

从命令执行到项目可运行，实测耗时取决于网络环境。本地缓存充足的情况下大概 10 秒左右完成，如果 pub 源需要冷启动拉取大量依赖，时间会拉到半分钟级别。比起完全手工创建再加依赖、再改结构，这个速度已经算很理想了。

4. 常见问题与排查技巧实录

4.1 模板误渲染与界定符冲突

我在开发过程中遇到最诡异的问题，是生成出来的某个 Dart 文件里出现一整段空白。排查了很久才发现，模板里有一段代码本来要保留双花括号作为字面量，结果被 mustache 当作变量插值处理了，渲染出来的字符串里多了一个空行。

处理方案是给 manifest 增加一个 raw 标记，被标记的文件不做渲染直接字节拷贝。这个方案的适用场景是：模板文件里包含大量非 mustache 语法、但确实需要原样输出的内容。另一种方案是使用定制界定符：

final template = Template(source, name: 'file', tagSyntax: TagSyntax.mustache);

mustache_template 支持通过 TagSyntax 切换不同符号组合。遇到模板中频繁出现双花括号且无法避免的情况，可以把界定符临时换成 {{=<% %>=}}，在文件开头指定：

{{=<% %>=}} // 包裹在注释里 <%projectName%>

这个写法很绕，我实际只在极少数特殊场景用过，最稳妥的还是 raw 标记和渲染白名单机制。

4.2 pub get 失败的典型诱因

模板生成没问题，但在 flutter pub get 这一步挂掉，是用户反馈里频率最高的问题。我排查时一般按这个顺序走：

第一，确认本机 Flutter SDK 版本和模板 pubspec 的 SDK 约束是否匹配。有些模板写的是 sdk: ">=3.0.0 <4.0.0"，但用户本机还是旧版 Flutter，就会报 pub get 失败。

第二，检查 pub 镜像源是否正常。新环境首次拉取依赖，网络不好时很容易中途断掉。生成器在这里能做的优化是检测到失败后提示用户重试，而不是直接让整个命令失败。

第三，看依赖之间的版本冲突。模板维护过程中某个状态管理库升级了主版本，和其他库产生冲突，这时候必须人工介入调整约束。

我建议生成器在 pub get 失败时做两件事：打印出错误输出全文，并告诉用户“请保留该目录，在项目目录下手动执行 flutter pub get 查看完整报错”。这比工具自身尝试掩盖错误要诚实得多。

4.3 模板升级与存量项目脱节

团队模板不是一成不变的，升级之后老项目的结构就和模板脱节了。这个问题没有完美解法，但可以做几件事缓解。

第一，在生成目录里埋入生成器版本信息。我会在项目根目录生成一个名为 .flutter_new_meta.json 的文件，记录生成器版本和模板版本。排查问题时能快速确认项目是用哪一版工具创建的。

第二，模板升级后跑一次“差异审计”。做法很简单：用新模板生成一个全新项目，再和存量项目做 diff，重点看 lib 目录和 pubspec.yaml。这个操作能直观看到升级带来的变化，避免盲目在存量项目上套模板。

第三，对文件级更新做谨慎处理。有些更新只是新增了某个依赖，可以直接在 pubspec.yaml 里加；但有些更新涉及目录结构调整，比如引入 feature 目录规范，就不能直接覆盖存量项目。这时候我会写迁移说明文档，做到可查、可回退。

4.4 Web 端下载 ZIP 的编码与体积问题

Web 端上线后收到过两个典型问题。第一个是 zip 包里的中文文件名乱码。archive 包在打包时对文件名默认处理可能不友好，我直接在写入前用 utf8.encode 编码文件名，保证中文正常。

第二个是下载下来的 zip 体积偏大。原因是模板里包含了 build 目录和安卓工程的编译产物，而这些根本不应该出现在产物里。我在打包器里加了过滤规则，跳过后缀为 .iml、.lock、build、.dart_tool 等开发期目录和文件，只交付真正需要的源码。

另外还有一个小问题是浏览器下载触发方式。如果直接打开 zip 链接，浏览器可能会尝试在线预览，表现为页面一片乱码。解决方法是设置响应头：

Content-Type: application/zip Content-Disposition: attachment; filename="demo_app.zip"

这样浏览器会强制下载而不是尝试打开。

最后再分享一个实际体会：模板这种所谓“一次性投入”的东西，其实最需要持续维护。工具写完之后，大部分工作来自模板仓库的迭代。我的习惯是每两周固定抽一点时间，用工具生成一个新项目跑一遍 analyze 和 test，确认整条链路没有因为依赖升级而断裂。这个简单的习惯帮我省掉了不少事，也让团队每次新建项目时的起点始终是一致的。后续如果你想把这个能力延伸到更多平台，比如同时生成桌面端或服务端代码，只要保持配置驱动、模板分离的骨架不变，扩展起来会很顺手。