跳转至

发布流程（RELEASE）

本文描述 flutter_zero 三仓库（flutter_zero_app / flutter_zero_cli / flutter_zero_template）的 开发、验证与发布流程。

核心原则：模板与 CLI 解耦发布。 模板可独立高频发版，CLI 在大多数情况下无需跟随发布； 两者通过 template_registry.json 的兼容桶机制衔接。

0. 前置知识

主题 文档
三仓库职责与架构 ARCHITECTURE.md
模板版本规则（SemVer bump） flutter_zero_template/VERSIONING.md
CLI 版本规则与兼容逻辑 flutter_zero_cli/VERSIONING.md
模板分发机制（registry） flutter_zero_template/template_registry.json

版本规则一句话：

  • PATCH(0.0.x) = 修 bug / 内容小修，不改契约 → CLI 躺着不动
  • MINOR(0.x.0) = 向下兼容新增（带默认值的可选变量、可选 brick） → CLI 躺着不动
  • MAJOR(x.0.0) = 破坏性（改 brick 变量契约 / 生成代码结构 / DI 锚点） → 必 bump minCliVersion

1. 整体流程

阶段 A：模板开发与验证（app → template → 本地验证）
阶段 B：CLI 调整（按需）
阶段 C：发布（解耦）—— 模板几乎总能不带 CLI 动

⚠️ 关键纠正：模板发版 ≠ CLI 必须发版。模板 PATCH/MINOR 时 CLI 完全不用发布， 因为 template_registry.json 会自动指向新模板，老 CLI 运行时自动拉到最新兼容版本。

阶段 A：模板开发与验证

A1. 在 flutter_zero_app 验证架构与模板

实现 / 验证业务、架构、模板结构。flutter_zero_app 是模板的验证项目，也是同步脚本的输入源。

A2. 同步模板到 flutter_zero_template

用同步脚本把 app 同步进 bricks/： 

cd flutter_zero_template
dart run scripts/sync_project_brick.dart
脚本会拷贝 + 内容替换（flutter_zero_app → {{name}}）+ 重命名 + 文件覆盖（见脚本内变量配置）。

A3. 本地用 mason 验证 brick 生成

确保两种 brick 都能正确渲染（需全局安装 mason：dart pub global activate mason_cli）： 

# 进入模板目录
cd flutter_zero_template

# （可选）初始化目录
mason init

# 将brick添加至mason本地运行
mason add feature --path brick/feature

# 验证feature模板生成
mason make feature --name demo --package_name demo
以上命令会在当前目录(flutter_zero_template)中生成一个目录，检查目录中内容是否正确。

A4. 用 CLI 本地模式端到端验证

通过环境变量让 CLI 从本地加载模板（不触网）： 

cd flutter_zero_cli
FLUZER_BRICKS_DIR=../flutter_zero_template/bricks dart run bin/fluzer.dart new demo
FLUZER_BRICKS_DIR=../flutter_zero_template/bricks dart run bin/fluzer.dart create demo_app

阶段 B：CLI 调整（按需）

B1. 修改 flutter_zero_cli

当模板的变量契约或 codemod 锚点（类名 / 方法名 / DI 注入区域）变化时，调整 CLI 代码。

B2. 验证

cd flutter_zero_cli
dart analyze
dart test
必须 0 issues + 全绿 才进入发布。

阶段 C：发布（解耦）

C1. 发布模板（核心步骤，通常独立于 CLI）

  1. 判定 bump：按 模板版本管理 决定 PATCH / MINOR / MAJOR。
  2. 打包： 
    cd flutter_zero_template
zip -r bricks.zip bricks     # 顶层直接是 bricks/...
  3. 发 GitHub Release（固定版本 URL，不要用 /latest 重定向链接）： 
    gh release create v1.0.1 bricks.zip --title "Templates v1.0.1"
# 得到固定链接：
# https://github.com/OWNER/REPO/releases/download/v1.0.1/bricks.zip
  4. 更新 template_registry.json（兼容性桶规则）：
  5. PATCH / MINOR → 只更新当前 minCliVersion 桶条目的 version + url（不新增条目）
  6. MAJOR → 新增一条（新的 minCliVersion），旧条目保留
  7. 推到 main（保证 raw URL 稳定可达）： 
    git add template_registry.json && git commit -m "chore: 更新模板注册表至 v1.0.1" && git push

✅ 到此，老 CLI 用户下次运行会自动拉到新模板，CLI 无需任何改动。

C2. 判断 CLI 是否要发版

场景 CLI 是否发版
模板 PATCH / MINOR 不发（registry 已指向新模板）
模板 MAJOR（要求更高 minCliVersion） 若 CLI 注入逻辑需改，则发；否则仅 registry 约束生效
CLI 自身有改动 / bug 修复 / 新功能 发

C3. 发布 CLI（仅当 C2 判定需要）

  1. 更新 lib/src/template/template_config.dart 的 cliVersion 常量（必须与 pubspec.yaml 同步）。
  2. 若模板 MAJOR，确认 resolveBrickLoader 的 minCliVersion 校验兼容。
  3. 重新跑 dart analyze + dart test。
  4. 发布： 
    cd flutter_zero_cli
dart pub publish

C4. 发布后验证

  • 版本提示：fluzer version 应能看到新版本提示（CLI 已发布到 pub.dev 后）。
  • 真实拉取：通过真实 registry（template_registry.json 指向的 Release 链接），验证 fluzer new 端到端拉到新模板并正确生成。

2. 发布前检查清单（Checklist）

模板发布前

  • [ ] 按 模板版本管理 判定 bump 类型
  • [ ] bricks.zip 已打包，顶层为 bricks/
  • [ ] GitHub Release 用固定版本 URL（非 /latest）
  • [ ] template_registry.json 已更新（PATCH/MINOR 改桶条目，MAJOR 新增条目）
  • [ ] template_registry.json 已推到 main

CLI 发布前

  • [ ] cliVersion 常量与 pubspec.yaml 版本一致
  • [ ] dart analyze 0 issues
  • [ ] dart test 全绿
  • [ ] 占位 URL 已替换为真实地址（见附录 3.1）
  • [ ] dart pub publish 成功

3. 附录

3.1 占位待替换（发布前必填）

位置：flutter_zero_cli/lib/src/template/template_config.dart

  • templateRegistryUrl → 真实 raw URL https://raw.githubusercontent.com/OWNER/REPO/main/template_registry.json
  • defaultTemplateZipUrl → 真实 Release 固定版本 URL（作为拉取失败时的兜底）
  • cliVersion → 与 pubspec.yaml 同步（每次 CLI 发版必改）

3.2 命令速查

用途 命令
同步模板 cd flutter_zero_template && dart run scripts/sync_project_brick.dart
本地验证 brick mason make feature --name demo --package_name demo
CLI 本地加载模板 FLUZER_BRICKS_DIR=../flutter_zero_template/bricks dart run bin/fluzer.dart new demo
CLI 查版本更新 fluzer version（发布后用全局命令）
发模板 zip -r bricks.zip bricks + gh release create vX.Y.Z bricks.zip + 更新 registry + push
发 CLI dart pub publish

文档维护：本流程随发布实践演进。若发现步骤与实际不符，优先更新本文与两份 versioning-xxx.md。