Finch CLI

finch 命令行工具负责处理运行中的应用之外的一切事务：搭建新项目、安装依赖、运行开发服务器、编译生产环境二进制文件，以及生成样板文件。它封装了常用的 Dart 命令，并加入了 Finch 特有的任务。

此外还有另一组独立的命令，仅在运行中的应用内部可用（migrate、route、language、info，以及你注册的任何自定义命令）——这些命令在 Commands 中介绍，不属于下方 finch -h 输出的一部分。这个区别很重要：finch <command> 在你的应用存在之前运行，而应用运行时命令会运行实际的 FinchApp 实例，因此可以操作路由、数据库和应用配置。关于两者是如何衔接的，请参阅 Running an Application 中关于传递参数的说明。

安装

dart pub global activate finch

命令

运行 finch -h 查看所有可用命令：

finch -h

✔ templates
        Show the list of available templates
✔ create
        Make new project
        -p, --path       Path of the project
        -n, --name       Name of project
        -d, --docker     Use docker
        -t, --template   Project template [simple, example,...]
✔ get
        Get packages of project, (dart pub get)
✔ runner
        Build runner of project, (dart pub run build_runner build)
✔ run
        Run project, (dart run)
        -p, --path       Path of app file
        -a, --args       Arguments for app file
✔ serve
        Serve project with file watcher
        -p, --path         Path of app file
        -a, --args         Arguments for app file
        -tp, --terminalPort Port for the terminal WebSocket that streams
                            console output and accepts remote commands
                            (default: 8282)
✔ build
        Build Project (dart compile exe)
        -c, --cli        Build for cli
        -a, --appPath    Path of app file
        -l, --langPath   Languages path
        -p, --publicPath Public path
        -w, --widgetPath Widgets path
        -e, --envPath    Envitoment file (.env) path
        -o, --output     Output path
        -t, --type       Type of build (zip, exe)
✔ migrate
        Migrate project to new version of Finch
        -c, --create     Create new project and move files
        -n, --name       Name of migration file (only for create option)
        -s, --sqlite     Migrate SQLite files
✔ test
        Unit test of project, (dart test)
        -r, --reporter   Set how to print test results
✔ make:controller
        Make new controller
        -n, --name       Name of controller
        -p, --path       Path of controller (default: ./lib/controllers/)
✔ make:service
        Make new service
        -n, --name       Name of service
        -p, --path       Path of service (default: ./lib/services/)
✔ make:middleware
        Make new middleware
        -n, --name       Name of middleware
        -p, --path       Path of middleware (default: ./lib/middleware/)
✔ make:migration
        Make new migration
        -n, --name       Name of migration
        -p, --path       Path of migration (default: ./lib/migrations/)
        -s, --sqlite     Create migration for SQLite

        -h, --help       Show the help
        -v, --version    Finch Version
        -u, --update     Update Finch

注意： 顶层的 finch migrate 仅支持创建迁移文件（--create --name ...）；即使加上 --sqlite，它也不会应用待处理的迁移。真正用于执行迁移的命令请参阅下方的运行迁移。

常用示例

使用 example 模板创建新项目

finch create -n my_app -t example

查看可用的项目模板

finch templates

获取可传递给 finch create -t <key> 的官方模板列表（每个模板都对应一个 <template>-finch-docker GitHub 仓库）。

使用文件监视器运行开发服务器

serve 命令会监视 widget 和语言文件的变更，并在不重启服务器的情况下自动重新加载：

finch serve

或指定入口文件：

finch serve -p lib/serve.dart

在底层，run/serve 会将你的应用作为子进程启动（dart run [--enable-asserts] [vm-service flags] <path> <args>），并在其之上于终端中保留一个小型交互式提示符——按 r 重启子进程，按 c 清屏，按 i 打印版本/Dart 信息，按 h 显示命令历史，按 q 退出。serve 还会在 --terminalPort（默认为 8282）上开启一个 WebSocket，镜像同一个提示符，这也是本地调试器在浏览器中连接的对象。

构建生产二进制文件

finch build -a lib/app.dart -o ./build/app

生成样板文件

finch make:controller -n Product
finch make:service -n Payment
finch make:middleware -n RateLimit
finch make:migration -n add_users_table
finch make:migration -n add_users_table -s   # 使用 SQLite 而不是 MySQL

创建迁移文件

finch migrate --create --name add_users_table
finch migrate --create --name add_users_table --sqlite

这只会在你配置的迁移路径下创建一个新的空迁移文件（pathMigrationMySQL/pathMigrationSQLite 的说明请参阅 Configuration）——具体的架构/数据变更需要你自己写入其中，写法请参阅 Database Migration。

运行迁移

应用迁移是一个应用运行时命令，而不是顶层的 finch 命令——它必须运行在你实际的 FinchApp 实例内部，这样才能使用你配置的数据库连接。可以通过 finch run/finch serve 传入 --args 来运行它，或者直接用 dart run 调用你的应用入口文件：

# 应用所有待处理的 MySQL 迁移
finch run --args="migrate --init"

# 应用所有待处理的 SQLite 迁移
finch run --args="migrate_sqlite --init"

# 使用 --and 在一次调用中串联两者（示例 Dockerfile 中即采用此写法）
finch run --args="migrate --init --and migrate_sqlite --init"

# 完全不通过 finch CLI 的等效写法
dart run lib/app.dart migrate --init

完整的应用运行时命令列表（route、language、info，以及你注册的任何自定义命令）请参阅 Commands；关于编写和回滚迁移，请参阅 Database Migration。

检查已注册的路由

route 同样是一个应用运行时命令，因此调用方式相同：

# 表格视图
finch run --args="route"

# 显示额外的列（controller、function、middlewares 等）
finch run --args="route --detail"

# 以 JSON 格式输出，例如传给其他工具处理
finch run --args="route --json"

本页内容