flutter-template-cli

基于自定义模板的 Flutter 脚手架，可选集成插件（GetX、slang 国际化）。

前置条件

• 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 \
  --getx \
  --skip-translation \
  --org com.acme \
  --platforms android,ios,web \
  --yes

| 参数 | 说明 | | -------------------- | --------------------------- | | --getx | 集成 GetX（路由、Home/Login 页面） | | --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】路由与模块
│   │   ├── routes/
│   │   │   ├── app_pages.dart
│   │   │   └── app_routes.dart
│   │   └── 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 时存在，包含路由和 Home/Login 模块 | | 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。选择 GetX 会额外添加 get，选择 slang 会添加 slang、slang_flutter。

配置文件

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

• 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/
        └── ...

slang 简单使用说明

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

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

说明

• 工具目前仅仅配置了一些简单模板, 后续可继续自定义完善扩展
• 运行前需确保 flutter 命令可用。