跨平台开发 / 系统课时

用 build_runner 持续生成

用 build_runner 持续生成

模型频繁变化时,手动记住每次都执行代码生成很容易漏。build_runner 提供一次性 build 和持续 watch 两种工作方式:前者适合明确的构建节点,后者适合开发期间增量生成;冲突输出则应单独判断,不要机械删除。

学习目标

  • 区分 build 与 watch 的使用场景
  • 把模型修改、代码生成和验证串成稳定开发节奏
  • 正确理解 --delete-conflicting-outputs 何时该用、何时不该用

build 与 watch 的工作方式

build 扫描当前输入并完成一轮生成,命令结束后进程退出;watch 会保持运行,监听相关文件变化,并在保存模型后执行增量构建。对于持续修改 Freezed 模型的开发过程,watch 能减少“改完模型却忘了重新生成”的概率。

build_runner 持续生成流程

一次性生成适合明确节点

需要在拉取代码、切换分支、CI 构建或准备提交前统一生成时,使用一次性 build:

bash
dart run build_runner build

预期结果:

text
命令完成后退出;需要更新的生成文件已写入磁盘,成功时退出码为 0。具体日志内容与耗时可能不同。

这种模式的优点是流程可控,尤其适合 CI:生成完成后再执行 dart analyze、测试或 Flutter 构建。如果模型没有变化,Builder 通常会复用已有构建信息,不需要人为删除生成文件。

watch 适合模型密集修改

开发过程中需要连续修改字段、注解和 fromJson 时,可以启动持续监听:

bash
dart run build_runner watch

预期结果:

text
进程保持运行并等待文件变化;保存受 Builder 关注的模型后会触发增量生成,直到手动结束进程。

启动 watch 后,不需要每改一次模型就重新敲命令。更稳定的节奏是:开始开发时启动一次监听,修改模型,等待本轮生成完成,再运行应用、分析器或测试。若你修改了 pubspec.yaml 中的生成器依赖或 Builder 配置,通常应先结束当前监听,完成依赖更新后再启动新的 watch。

冲突输出不要默认删除

build_runner 有时会报告 conflicting outputs,常见于切换分支、生成规则变化,或磁盘上已有同名文件但当前构建状态无法确认它由 Builder 管理。此时可以使用:

bash
dart run build_runner build --delete-conflicting-outputs

预期结果:

text
确认属于冲突生成产物的输出可被删除并重新生成;命令成功时退出码为 0。实际被处理的文件取决于当前项目状态。

这个选项不是“修复所有生成失败”的万能开关。它允许构建器删除与预期生成输出冲突的文件,所以使用前要确认这些路径确实应该由代码生成器拥有,不能把手写源码放到生成器的输出路径上。

把生成纳入固定开发节奏

本地开发可以保持简单:长时间改模型时用 watch,准备提交或需要一次干净检查时用 build。CI 则更适合一次性 build,因为它会自然结束,便于后续步骤根据退出码判断是否继续。

当生成失败时,先看第一条明确错误并定位到源模型;只有错误明确指向已有冲突输出时,才考虑 --delete-conflicting-outputs。把“修改源文件 → 生成 → 分析或测试”作为一个完整闭环,比反复手删 .g.dart、.freezed.dart 更稳定,也更容易在团队中复现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 build_runner 持续生成

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通