flutter-template-cli

基于自定义模板的 Flutter 脚手架，支持两套架构初始化：

• 模板 1：GetX 全家桶
• 模板 2：get_it + signals + AutoRoute

前置条件

• Node.js >= 18
• Flutter SDK（命令行可用：flutter --version）

安装与使用

本工具发布到 npm，推荐使用 npx 每次拉取最新版本执行。

方式一：npx（推荐，始终最新）

npx --yes flutter-template-cli@latest create my_app

查看帮助：

npx --yes flutter-template-cli@latest --help

方式二：全局安装（可选）

npm i -g flutter-template-cli
flutter-template create my_app

更新全局安装版本：

npm i -g flutter-template-cli@latest

方式三：本地开发运行

cd flutter-template
npm install
npm run init-config
npm run create -- my_app

更新 CLI

使用 npx 时，执行时指定 @latest 即可拿到最新版本：

npx --yes flutter-template-cli@latest create my_app

全局安装用户需要手动更新：

npm i -g flutter-template-cli@latest

常用参数示例

npx --yes flutter-template-cli@latest create my_app \
  --architecture getx \
  --skip-translation \
  --org com.acme \
  --platforms android,ios,web \
  --yes

| 参数 | 说明 | | -------------------- | --------------------------- | | --architecture | 架构方案：getx 或 getit | | --getx | 兼容旧参数，等价于 --architecture getx | | --skip-translation | 不启用 slang 国际化（默认启用） | | --org | 组织 ID，如 com.example | | --platforms | 平台，逗号分隔，如 android,ios,web | | --output <dir> | 项目输出目录 | | --yes / -y | 非交互模式 |

生成项目结构说明

执行 flutter-template create my_app 后，会在指定目录（默认当前目录）生成 my_app/ 项目，结构如下。

目录结构概览

my_app/
├── android/              # Android 平台
├── ios/                  # iOS 平台
├── web/                  # Web 平台
├── lib/
│   ├── main.dart         # 入口
│   ├── config/           # 配置（主题、环境变量）
│   │   ├── theme.dart
│   │   └── env.dart
│   ├── network/          # 网络层（Dio、拦截器、异常）
│   │   ├── http_client.dart
│   │   ├── http_config.dart
│   │   ├── http_interceptor.dart
│   │   ├── http_exception.dart
│   │   ├── api_response.dart
│   │   └── api_path.dart
│   ├── utils/            # 工具类
│   │   ├── logger.dart
│   │   ├── sp_util.dart
│   │   ├── toast_util.dart
│   │   ├── permission_util.dart
│   │   ├── color_util.dart
│   │   ├── text_util.dart
│   │   ├── eventbus_util.dart
│   │   └── mqtt_util.dart
│   ├── components/       # 通用 UI 组件
│   │   ├── normal_button.dart
│   │   ├── normal_field.dart
│   │   ├── normal_image.dart
│   │   ├── normal_select.dart
│   │   ├── normal_appBar.dart
│   │   ├── normal_page.dart
│   │   └── background_page.dart
│   ├── const/            # 常量
│   │   └── const.dart
│   ├── generator/        # 代码生成（资源等）
│   │   └── assets.dart
│   ├── app/              # 路由层（GetX 或 AutoRoute）
│   │   ├── routes/
│   │   │   ├── app_pages.dart
│   │   │   └── app_routes.dart
│   │   └── router/
│   │       └── app_router.dart
│   ├── di/               # 【仅模板2】get_it 依赖注入
│   │   └── service_locator.dart
│   ├── features/         # 【仅模板2】业务页面与 signals 状态
│   │   └── counter/
│   │   └── modules/
│   │       ├── home/
│   │       └── login/
│   └── lang/             # 【仅 slang】国际化
│       ├── en.i18n.json
│       ├── zh.i18n.json
│       └── i18n.g.dart    # 生成
├── test/
├── pubspec.yaml
├── analysis_options.yaml
└── slang.yaml            # 【仅 slang】slang 配置

主要模块说明

| 模块 | 说明 | | ------------- | -------------------------------------- | | config/ | 主题色、环境变量、API 基础地址等 | | network/ | Dio 封装、HTTP 拦截器、统一异常、响应模型 | | utils/ | 日志、本地存储、Toast、权限、颜色/文本工具、EventBus、MQTT | | components/ | 通用按钮、输入框、图片、选择器、AppBar、页面容器等 | | app/ | 路由相关实现（GetX 路由或 AutoRoute） | | di/ | 仅模板2，集中注册 get_it 依赖 | | features/ | 仅模板2，按功能组织页面和 signals 状态 | | lang/ | 仅在选择 slang 时存在，多语言文案与生成代码 |

内置依赖

创建时会自动添加：dio、shared_preferences、logger、flutter_smart_dialog、permission_handler、flutter_chen_refresh、cached_network_image、event_bus、flutter_screenutil、intl、camera、flutter_inappwebview、path_provider、mqtt_client。

• 模板 1（GetX）：额外添加 get
• 模板 2（get_it + signals + AutoRoute）：额外添加 get_it、signals、signals_flutter、auto_route，并添加开发依赖 auto_route_generator、build_runner
• 如启用国际化：额外添加 slang、slang_flutter

架构模板选择

交互式（推荐）

npx --yes flutter-template-cli@latest create my_app

CLI 会提示你选择：

• 1) GetX 全家桶（路由 + 状态 + 依赖）
• 2) get_it + signals + AutoRoute

非交互式

# 模板 1
npx --yes flutter-template-cli@latest create my_app --architecture getx --yes

# 模板 2
npx --yes flutter-template-cli@latest create my_app --architecture getit --yes

模板 2 会自动生成示例页面：lib/features/counter/counter_page.dart。

配置文件

默认按以下顺序查找配置：

• flutter-template.config.json
• flutter-template.config.yaml / .yml
• .flutter-template.config.json / .yaml / .yml

也可通过 --config 指定：

npm run create -- my_app --config ./my.config.json

配置字段简述

• flutterCommand: 可选，默认 flutter
• defaults: flutter create 默认参数
• prompts: 自定义交互问题
• templateSources: 模板拷贝规则
• postCreate: 创建完成后执行的命令

模板变量

templateSources（interpolate: true）和 postCreate 中可用 {{变量}}：

• projectName、projectDir、org、description
• template、platforms、androidLanguage、iosLanguage
• 以及 prompts 中自定义字段
• addGetx、addSlang、useGet、useSlang、packageName

注意事项

GetX + slang 切换语言

切换语言需同时调用 slang 和 GetX触发重建

// 1. 先调用 slang 切换
LocaleSettings.setLocale();
// 2. 再同步 GetX 的 locale，触发get顶层的重建
Get.updateLocale();

GetX 简单使用说明

项目如果采用 GetX 进行路由和状态管理，目录结构为 lib/app/modules/，每个模块包含 bindings、controllers、views。

get_cli 安装

dart pub global activate get_cli
# 或
flutter pub global activate get_cli

创建页面（自动添加路由）

在 lib/app/modules/ 下创建新页面，会同时生成 controller、view、binding，并自动注册路由：

# 在项目根目录执行
get create page:profile

会生成 lib/app/modules/profile/：

profile/
├── bindings/profile_binding.dart
├── controllers/profile_controller.dart
└── views/profile_view.dart

路由会自动加入 app_pages.dart 和 app_routes.dart。

在指定模块下创建子页面

get create page:detail on home

在 home 模块下创建 detail 子页面。

单独创建 Controller / View

# 在指定模块下新增 controller
get create controller:dialog on home

# 在指定模块下新增 view
get create view:dialog on home

当然也可自己手动创建

项目结构说明

lib/app/
├── routes/
│   ├── app_pages.dart   # 路由配置
│   └── app_routes.dart  # 路由常量
└── modules/
    ├── home/
    │   ├── bindings/    # 依赖注入
    │   ├── controllers/
    │   └── views/
    └── login/
        └── ...

get_it + signals + AutoRoute 简单使用说明

当你选择模板 2 时，项目会提供以下基础结构：

• lib/di/service_locator.dart：依赖注册
• lib/app/router/app_router.dart：AutoRoute 路由定义
• lib/features/counter/：signals 示例页面与状态

扩展示例（新增页面）

1. 在 lib/features/xxx/ 下新增页面和状态
2. 在 service_locator.dart 注册依赖
3. 在 app_router.dart 新增路由

建议所有状态优先使用 signals，页面监听使用 Watch。

模板 2 默认采用 AutoRoute 注解代码生成，CLI 创建后会自动执行：

dart run build_runner build --delete-conflicting-outputs

同时也支持无代码生成写法（RootStackRouter.build + NamedRouteDef），模板中的路由文件有注释说明两种方式都可用。

slang 简单使用说明

项目如果采用 slang 进行国际化，目录结构为 lib/lang/，简单包含了中英 en.i18n.json、zh.i18n.json两种语言示例。

也是根据语言生成相应文件, 具体使用参考 https://pub.dev/packages/slang

说明

• 工具目前仅仅配置了一些简单模板, 后续可继续自定义完善扩展
• 运行前需确保 flutter 命令可用。
• 给大模型 Agent 的项目说明文档见 AGENT_GUIDE.md