pubspec.yaml 中的 Finch 配置

pubspec.yaml 中的 finch 部分向 Finch CLI 提供项目设置。finch run、finch serve、finch build、finch migrate --create 和 finch make:migration 等命令使用此部分查找入口文件、项目资源、构建输出路径以及创建迁移文件的目录。

这些设置不同于 FinchConfigs。finch 部分控制命令行工具，而 FinchConfigs 保存应用程序运行时设置，例如端口、数据库配置和静态文件目录。

完整示例

# Finch configuration
# See https://pub.dev/packages/finch for more details
# Here you can customize paths and settings for your Finch application
# They will be used by Finch CLI commands to run, build, serve, migrate, etc.
# Adjust these settings as needed for your project structure
finch:
  # Main path of the application
  app: ./lib/app.dart
  # Path of serve file while developing
  serve: ./lib/serve.dart
  # Path of languages files
  languages_path: ./lib/languages
  # Type of languages files
  languages_type: json
  # Path of templates (widgets) files
  widgets_path: ./lib/widgets
  # Type of templates (widgets) files
  widgets_type: j2.html
  # Path of migrations files for different databases
  mysql_migrate:
    path: ./migrations
    type: sql
  # Path of migrations files for different databases
  sqlite_migrate:
    path: ./lib/dart_migration
    type: dart
  build_output: ./build_example
  public_path: ./public

相对路径以执行 finch 命令时的当前目录为基准解析。通常应从包含 pubspec.yaml 的项目根目录执行命令。创建 ProjectCommands 时，CLI 同样会在当前目录中查找 pubspec.yaml 并加载其中的 finch 部分。

应用程序入口文件

app

指定以下命令使用的主应用程序文件：

finch run

在上面的示例中，CLI 对 ./lib/app.dart 执行 dart run。如果提供 --path 或 -p，命令行中的值将取代 app：

finch run --path ./lib/another_app.dart

如果未配置 app，CLI 会在 bin、lib 和 src 等常用目录中查找 app.dart、server.dart 等文件名。如果仍未找到文件，CLI 会提示用户输入路径。

注意：在当前实现中，finch build 不会直接读取 app 键。请使用 --appPath 或 -a 选择构建入口文件。否则，build 会先检查旧的内部 path 设置，然后回退到 ./lib/app.dart。

serve

指定以下命令使用的开发环境入口文件：

finch serve

除了运行所选文件，此命令还会启用 Dart VM Service，以支持开发和重新加载流程。--path 或 -p 选项的优先级高于 serve：

finch serve --path ./lib/watcher.dart

配置的文件必须真实存在于项目中，并提供适合运行应用程序的入口点。

语言文件

languages_path

指定翻译文件所在的目录。如果没有此键，CLI 默认使用 ./lib/languages。

finch build 命令会将此目录复制到构建输出中的 lib/languages。--langPath 或 -l 选项会在当前构建中覆盖此设置：

finch build --langPath ./lib/languages

如果路径为空或目录不存在，则跳过复制语言文件的步骤。

languages_type

指定翻译文件的扩展名，不包含开头的点。对于 fa.json 和 en.json 等文件，应使用 json。

当应用程序内部构建需要将翻译转换为 Dart 时，LanguageToDart 仅读取具有此扩展名的文件，并在 languages_path 中生成 language_dart.g.dart。默认值为 json。

模板

widgets_path

指定 Jinja 模板目录。如果没有此键，CLI 默认使用 ./lib/widgets。

finch build 命令会将此目录复制到构建输出中的 lib/widgets。--widgetPath 或 -w 选项会在当前构建中优先使用：

finch build --widgetPath ./lib/widgets

如果路径为空或目录不存在，则跳过复制模板的步骤。

widgets_type

指定模板扩展名，不包含开头的点。对于 home.j2.html 等文件，正确的值是 j2.html。

当应用程序内部构建将模板转换为 Dart 时，WidgetToDart 会将匹配此扩展名的文件转换为模板 map，并在 widgets_path 中创建 widget_dart.g.dart。CLI 对此转换的默认值为 html。

数据库迁移

mysql_migrate

包含创建 MySQL 迁移文件的设置：

mysql_migrate:
  path: ./migrations
  type: sql

• path：创建新迁移文件的目录。
• type：文件扩展名和迁移模板类型，通常为 sql。

finch migrate --create 和 finch make:migration 会读取这些值：

finch migrate --create --name create_users
finch make:migration --name create_users

生成的文件名包含时间戳、迁移名称和配置的扩展名。finch make:migration 的 --path 或 -p 选项可以为当前调用覆盖目录。

sqlite_migrate

包含创建 SQLite 迁移文件的设置：

sqlite_migrate:
  path: ./lib/dart_migration
  type: dart

提供 --sqlite 或 -s 时，CLI 会读取此部分而不是 MySQL 设置：

finch make:migration --sqlite --name create_books
finch migrate --create --sqlite --name create_books

在示例项目中，dart 类型会在 ./lib/dart_migration 中创建 Dart 迁移文件。此部分指定 CLI 创建新文件的位置。运行时执行已注册迁移所使用的路径来自应用程序配置以及 FinchApp 中的迁移注册。

构建输出

build_output

指定 finch build 的默认输出目录：

build_output: ./build_example

构建输出包含位于 lib/app.exe 的可执行文件，并在资源存在时包含 public 文件、语言文件和模板的副本。--output 或 -o 选项的优先级更高：

finch build --appPath ./lib/app.dart --output ./release

如果 build_output 中配置的目录已存在，CLI 会删除并重新创建该目录以进行新的构建。但是，如果通过 --output 提供的自定义路径已经存在，构建会停止以避免覆盖它。

如果没有此键，默认值为 ./finch_build。

Public 文件

public_path

指定构建步骤中 CSS、JavaScript、图像和字体等 public 文件的源目录：

public_path: ./public

如果此目录存在，finch build 会将其复制到构建输出的 public 目录。build 命令的 --publicPath 或 -p 选项具有更高优先级：

finch build --publicPath ./public

如果没有此键，默认值为 ./public。此设置只控制构建期间复制的源目录。运行中的应用程序所提供的静态文件目录仍必须通过 FinchConfigs.publicDir 配置。

配置优先级

当 CLI 命令提供对应选项时，Finch 按以下顺序选择值：

1. 命令行中提供的选项
2. pubspec.yaml 的 finch 部分中的值
3. Finch CLI 的内部默认值

例如，在以下命令中，--output 会取代 build_output，而 --appPath 会选择构建入口文件：

finch build \
  --appPath ./lib/app.dart \
  --output ./release \
  --publicPath ./public \
  --langPath ./lib/languages \
  --widgetPath ./lib/widgets

建议将稳定的项目路径保存在 pubspec.yaml 中，并在临时使用不同路径时通过命令行选项覆盖。