Flutter 命令行工具使用说明

这是一个基于 Node.js + Commander 的 Flutter 命令行工具，包含两个主要命令：

• flutter-build：用于快速构建 apk / aab，并按 应用名 + 版本号 + 日期 + 构建模式 + 环境 自动重命名输出文件
• flutter-router：用于自动扫描项目中的 Dart 文件，生成路由相关文件

一、功能特性

flutter-build 命令

• ✅ 支持 apk / aab 打包
• ✅ 支持 debug / profile / release 编译模式
• ✅ 支持接口环境区分：test / prod
• ✅ 自动从 pubspec.yaml 读取应用名和版本号
• ✅ 自动生成带日期的输出文件名
• ✅ release 模式自动开启混淆与符号分离

flutter-router 命令

• ✅ 自动扫描项目中的 Dart 文件，查找带有 @RouteE 注解的类
• ✅ 自动生成路由导入文件：router.p.dart
• ✅ 自动生成路由管理文件：router.r.dart
• ✅ 支持路由转场动画配置
• ✅ 支持初始路由设置
• ✅ 支持忽略特定路由

二、前置条件

1. 环境要求

• Node.js ≥ 14
• Flutter SDK 已正确安装
• 当前目录必须包含 pubspec.yaml

三、安装方式

全局安装

npm install -g @hyou/flutter-cli

项目内安装

npm install @hyou/flutter-cli --save-dev

四、命令行用法

1. flutter-build 命令

flutter-build <type> [options]

参数说明

1️⃣ 必填参数

| 参数 | 说明 | | ------ | ------------------ | | type | 打包类型：apk 或 aab |

2️⃣ 编译模式（必须且只能选择一个）

| 参数 | 说明 | | --------------- | ---------- | | -d, --debug | Debug 模式 | | -p, --profile | Profile 模式 | | -r, --release | Release 模式 |

3️⃣ 接口环境（必填）

| 参数 | 说明 | | ----------------- | -------------------- | | -e, --env <key> | 接口环境：test 或 prod |

2. flutter-router 命令

flutter-router

功能说明

• 自动扫描项目中的 Dart 文件，查找带有 @RouteE 注解的类
• 生成路由相关文件：
  • lib/src/router/router.p.dart：路由页面导入统一管理
  • lib/src/router/router.r.dart：路由管理

注解参数

| 参数 | 说明 | 默认值 | | ------------- | --------------------- | --------------- | | name | 路由名称 | 必填 | | initialRoute | 是否为初始路由 | false | | transition | 转场动画 | rightToLeft | | ignore | 是否忽略该路由 | false |

注解使用示例

@RouteE(name: '/home')
class HomePage extends StatelessWidget {
  // ...
}

@RouteE(name: '/detail', transition: 'leftToRight')
class DetailPage extends StatelessWidget {
  // ...
}

@RouteE(name: '/', initialRoute: 'true')
class SplashPage extends StatelessWidget {
  // ...
}

五、使用示例

1️⃣ 打包 Debug APK（测试环境）

flutter-build apk --debug --env test

2️⃣ 打包 Profile APK（生产环境）

flutter-build apk --profile --env prod

3️⃣ 打包 Release AAB（生产环境）

flutter-build aab --release --env prod

4️⃣ 生成路由文件

flutter-router

六、输出文件说明

1. flutter-build 命令输出

默认输出目录

build/app/outputs/flutter-apk/

文件命名规则

{AppName}_{VersionName}-{VersionCode}_{YYYYMMDD}_{mode}-{env}.{type}

示例

MyApp_1.2.0-45_20251224_release-prod.apk

命名来源说明

| 字段 | 来源 | | ------------- | -------------------------------- | | AppName | pubspec.yaml 中的 name（下划线转驼峰） | | VersionName | version: x.y.z+code 中的 x.y.z | | VersionCode | version 中的 code | | YYYYMMDD | 构建日期 | | mode | debug / profile / release | | env | test / prod |

2. flutter-router 命令输出

输出文件

| 文件路径 | 说明 | | -------------------------------- | ---------------------- | | lib/src/router/router.p.dart | 路由页面导入统一管理 | | lib/src/router/router.r.dart | 路由管理 |

七、Release 模式额外行为

当使用 --release 时，自动追加以下 Flutter 参数：

--obfuscate
--split-debug-info=./symbols

生成的符号文件位于：

./symbols/

八、常见错误提示

❌ 未选择编译模式

请选择编译模式

❌ 同时选择多个模式

只能选择一种编译模式

❌ 接口环境错误

请选择正确的接口环境: test | prod

❌ 非 Flutter 项目目录

请确保当前目录下有pubspec.yaml文件

九、注意事项

• Windows 平台使用的是 move 命令重命名文件
• 如需兼容 macOS / Linux，可将 move 替换为 mv
• 脚本默认只处理 Android 构建产物