flutter_release_cli 0.1.19

Global CLI for Flutter release scaffolding and Fastforge-based publishing.

flutter_release_cli

flutter_release_cli 是一个面向 Flutter 项目的全局发布工具， 用于快速初始化发布脚手架，并基于 Fastforge 执行 Android / iOS 发布流程。

功能概览

• 一条命令初始化项目发布文件（配置、脚本、文档、可选 CI）
• 发布前环境与凭证健康检查
• 统一版本号递增（major / minor / patch / build）
• 支持 android / ios / all + test / prod 发布组合
• 统一清理发布临时目录与产物目录

开发文档

• CLI 颜色输出规范：docs/cli-color-style-guide.md

全局安装

方式一：本地路径安装（推荐）

dart pub global activate --source path /path/to/flutter_release_cli

例如在当前仓库根目录：

dart pub global activate --source path .

方式二：发布到 pub 后安装

dart pub global activate flutter_release_cli

命令总览

fr init --with-ci
fr doctor
fr list
fr bump build
fr release android test
fr release ios prod
fr clean --artifacts
fr version

发布 flutter_release_cli 自身到 pub.dev（交互式）

仓库提供了一个交互式脚本，可一步一步选择版本递增、检查与发布动作：

sh scripts/publish_wizard.sh

向导会依次引导你：

• 选择发布方式（本地打包 / 发布到 pub.dev）
• 处理 publish_to（若为 none 会提示修正）
• 选择版本策略（major/minor/patch/手动/不改）
• 自动同步 pubspec.yaml 与 lib/src/core/cli_version.dart 版本号
• 选择是否执行 pub get、analyze、test
• 本地模式：执行 dart pub global activate --source path .，并自动生成可执行 snapshot（确保 fr 命令立即生效）
• pub.dev 模式：执行 dart pub publish --dry-run，并二次确认后 dart pub publish --force
• 可选创建 git commit/tag 并推送

命令说明

1) 初始化脚手架

fr init [--template fastforge] [--with-ci] [--force]

参数说明：

• --template：当前仅支持 fastforge
• --with-ci：额外生成 GitHub Actions 发布工作流
• --force：覆盖已存在文件（默认不覆盖）

fr init 会生成/维护以下内容：

• distribute_options.yaml
• .release/secrets.local.yaml
• .release/config.yaml
• scripts/release.sh
• scripts/bump_version.sh
• docs/release.md
• .github/workflows/release.yml（使用 --with-ci 时）

并自动补齐：

• .gitignore（确保本地 secrets 与产物目录不入库）
• pubspec.yaml 中的 scripts 命令映射

2) 环境健康检查

fr doctor

会检查：

• flutter / dart / fvm / fastforge 可用性
• distribute_options.yaml 结构与 release 定义
• iOS 场景下的 macOS / Xcode 条件
• 发布目标所需凭证是否可用
• 配置中是否存在敏感信息硬编码风险

3) 列出发布配置

fr list

输出 distribute_options.yaml 中的 release 与 job 列表。

4) 版本号递增

fr bump <major|minor|patch|build>

示例：

fr bump build
fr bump patch

5) 执行发布

fr release <android|ios|all> <test|prod> [options]

可选参数：

• --skip-analyze：跳过 flutter analyze
• --skip-clean：跳过 flutter clean 与 flutter pub get
• --verbose：打印更详细命令日志
• --build-only：预留参数（当前未启用）
• --upload-only：预留参数（当前未启用）

说明：

• ios 发布要求在 macOS 上执行
• all 会按顺序执行 android 再 ios
• 仅会校验“本次发布目标”对应的凭证需求

6) 清理

fr clean [--artifacts]

• 默认清理：.release/.tmp
• 增加 --artifacts：同时清理 dist/

7) 查看 CLI 版本

fr version

密钥与配置优先级

凭证读取优先级：

1. 环境变量
2. .release/secrets.local.yaml
3. distribute_options.yaml 中变量默认值

建议：

• CI 中使用环境变量
• 本地开发使用 .release/secrets.local.yaml
• 不要将真实密钥写入仓库

典型使用流程

# 1) 安装
dart pub global activate --source path .

# 2) 初始化脚手架
fr init --with-ci

# 3) 填写本地密钥
# 编辑 .release/secrets.local.yaml

# 4) 做一次环境检查
fr doctor

# 5) 执行发布
fr release android test
fr release ios prod

注意事项

• 默认发布引擎是 Fastforge
• --build-only / --upload-only 目前为保留参数，暂不可用
• 如果命令未找到，请确认 ~/.pub-cache/bin 已加入 PATH