build_runner的核心概念和各个 builder 的作用

Dart build system（build_runner） 的核心概念和各个 builder 的作用。

---

🧱 Dart build.yaml 基础

• build.yaml 是 Dart build_runner 使用的配置文件。

• 它定义了 builders（构建器） —— 用于在编译或构建阶段自动生成或转换文件。

• 每个 builder 都需要：

  • import: 构建器所在的 Dart 文件
  • builder_factories: 构造函数名称
  • build_extensions: 输入输出文件映射关系
  • auto_apply: 自动应用的范围
  • 可选项如 defaults.generate_for、build_to

文档参考 👉 pub.dev/packages/bu…

---

🔧 各个 builder 说明

1️⃣ copyBuilder

copyBuilder:
  import: "package:example/builder.dart"
  builder_factories: ["copyBuilder"]
  build_extensions: {".txt": [".txt.copy"]}
  build_to: source
  auto_apply: root_package

功能说明：

• 把 .txt 文件复制成 .txt.copy
• 例如 notes.txt → notes.txt.copy
• build_to: source 表示生成在源代码目录（不是 .dart_tool 临时目录）
• 仅应用在当前包 (root_package)

---

2️⃣ resolvingBuilder

resolvingBuilder:
  import: "package:example/builder.dart"
  builder_factories: ["resolvingBuilder"]
  build_extensions: {".dart": [".dart.info.json"]}
  build_to: source
  auto_apply: root_package
  defaults:
    generate_for:
      include:
        - web/**

功能说明：

• 处理 .dart 文件，生成 .dart.info.json
• 输出包含 Dart 源码的分析或信息文件（例如 AST、依赖）
• 仅对 web/ 目录下的 Dart 文件生效
• 输出文件与源文件同目录

---

3️⃣ cssBuilder

cssBuilder:
  import: "package:example/builder.dart"
  builder_factories: ["cssBuilder"]
  build_extensions: {"$package$": ["web/generated.css"]}
  auto_apply: root_package

功能说明：

• 以整个包为输入（$package$ 特殊标识）
• 生成单一文件 web/generated.css
• 通常用于扫描项目内样式文件或配置并合并生成统一的 CSS 文件

---

4️⃣ textBuilder

textBuilder:
  import: "package:example/builder.dart"
  builder_factories: ["textBuilder"]
  build_extensions: {"^assets/{{}}.json": ["lib/generated/{{}}.dart"]}
  auto_apply: root_package
  build_to: source

功能说明：

• 读取 assets/ 下的 .json 文件

• 按模板生成对应的 Dart 源文件：

  assets/config.json → lib/generated/config.dart
  

• 常用于将资源文件（如配置、语言包）转成 Dart 代码方便直接引用

---

🧭 参数释义简表

字段	含义
import	构建器定义所在的 Dart 文件
builder_factories	构造构建器实例的函数名
build_extensions	输入 → 输出 文件映射
build_to	输出位置（source = 源目录，cache = 构建缓存）
auto_apply	自动应用范围（root_package/dependents/none）
defaults.generate_for	指定只在哪些文件或目录上运行
$package$	表示整个包为输入
{{}}	模板占位符，用于动态文件名映射

---

📘 总结要点

• 每个 builder 对应一个独立任务（复制、生成、解析、聚合）。

• build_extensions 是核心，定义输入输出关系。

• build_runner 会根据 build.yaml 自动执行构建链。

• 运行命令：

  dart run build_runner build
  # 或
  flutter pub run build_runner build
  

---