Flutter脚本执行插件script_runner的使用

简介

Dart Script Runner 是一个通用的脚本运行器，适用于任何类型的项目。它允许你在一个可移植且简单的配置中运行所有与项目相关的脚本和命令。

用途

你可以使用它来链式调用多个命令以统一构建过程、格式化和检查你的文档等。相比于 make，它的优势在于自动生成文档，并能自动从包含 pubspec.yaml 的目录加载脚本，而不需要手动查找项目的根目录。

这个项目受到 NPM 在 package.json 中 scripts 部分的启发，旨在类似地工作，但可以根据需要进行更具体的定制。

特性

• 易用：提供了一个易于使用的配置，类似于 NPM 在 package.json 中的 scripts 部分。
• 便携：脚本是便携的，可以相互引用，最大化创建可配置的脚本执行顺序和依赖关系的灵活性。你不必在 Dart 项目中，只需在任何文件夹中添加一个 script_runner.yaml 文件即可。
• 自我记录：无需记录如何加载不同类型的脚本或创建自定义脚本加载器，将所有运行器统一到一个配置中，允许你按需调用一切，并通过 scr -h 提供自动生成的文档。

入门指南

你可以全局安装此包以获得最简单的使用体验。

pub global activate script_runner

激活后，你可以使用提供的 scr 可执行文件直接调用当前项目中的脚本。

scr my-script ...args

你也可以将此包作为依赖项安装并构建/运行自己的脚本列表（但这有什么意义呢？）

内置命令

要获取帮助，包括当前目录中所有可用脚本的列表，请运行：

scr -h

要列出所有脚本，并能够搜索，请使用：

scr -ls # 查看所有脚本
scr -ls terms # 搜索 "terms"

使用方法

普通用法（配置文件）

在 pubspec.yaml 中添加 script_runner 配置，或者在项目的根目录下使用单独的配置文件 script_runner.yaml。如果你更喜欢 JSON 格式，也可以使用 JSON 文件。

一个基本的例子如下：

script_runner:
  scripts:
    - doc: dart doc
    - publish: dart pub publish
    - deploy: doc && publish
    - auto-fix: dart fix --apply

完整的配置结构如下：

# 仅在 pubspec.yaml 内使用此键。否则，不需要
script_runner:
  # 运行所有脚本时使用的 shell。（可选，默认为操作系统 shell）
  shell: /bin/sh
  # 为每个操作系统定义不同的 shell，未指定时回退到 "default"：
  # （可选）
  shell:
    default: /bin/sh
    windows: cmd.exe
    macos: /bin/sh
    linux: /bin/sh
  # 脚本运行的工作目录。（可选）
  cwd: .
  # 添加到运行脚本的环境变量。（可选）
  env:
    MY_ENV: my-value
    # ...
  # 打印帮助信息时，允许的最大字符数
  line_length: 80
  # 脚本支持简短格式配置或更详细的配置
  scripts:
    # 简短格式 - 仅名称 + 命令及参数：
    - my-short-script: my_scr arg1 arg2 arg3 && echo 'Done!'

    # 更详细的配置，提供更多配置选项
    - name: my-script
      # 可选 - 将用于 `scr -h` 中的文档
      description: Run my script
      # 可选 - 覆盖根级别配置
      cwd: .
      # 可选 - 覆盖根级别配置
      env:
        MY_ENV: my-value
        # ...
      # 设置为 `false` 以隐藏命令本身，只显示输出
      display_cmd: true
      # 要运行的命令。可以直接在此处提供参数，或将其拆分为 `cmd` 和 `args` 列表。
      cmd: my_scr 'arg1'
      # 可选 - 如果提供，将在 CLI 调用脚本时附加为 `cmd` 的参数
      args:
        - arg2
        - arg3

对于此配置，运行 scr my-script 将运行适当的脚本，填充环境变量并根据需要更改工作目录。

更多参数可以在调用脚本时传递，这些参数将被管道传递给原始的 cmd。

高级用法（Dart 导入）

如果你想在 Dart 中动态构建自己的配置，可以导入该包并创建自己的运行器和脚本：

import 'package:script_runner/script_runner.dart';

void main() {
  // 直接从配置中运行脚本，类似于运行 `scr`
  runScript('my-script', ['arg1', 'arg2'])

  // 构建自己的配置和脚本并按需运行：
  final runner = ScriptRunnerConfig(
    shell: '/bin/zsh',
    scripts: [
      RunnableScript(
        name: 'my-script',
        cmd: 'echo',
        args: ['Hello world'],
      ),
    ],
  );

  runner.scriptsMap['my-script'].run();
}

示例代码

pubspec.yaml 示例配置

script_runner:
  scripts:
    - build: flutter build apk
    - test: flutter test
    - format: dart format lib/
    - analyze: dart analyze
    - deploy: build && test && flutter pub publish

script_runner.yaml 示例配置

script_runner:
  shell: /bin/bash
  cwd: ./project_root
  env:
    FLUTTER_HOME: /path/to/flutter
  scripts:
    - name: build
      description: Build the Flutter app
      cmd: flutter build apk
    - name: test
      description: Run all tests
      cmd: flutter test
    - name: format
      description: Format all Dart files
      cmd: dart format lib/
    - name: analyze
      description: Analyze the codebase
      cmd: dart analyze
    - name: deploy
      description: Deploy the project
      cmd: scr build && scr test && flutter pub publish

完整示例 Demo

假设你有一个 Flutter 项目，想要集成 script_runner 来简化开发流程。以下是完整的步骤和配置示例：

1. 安装 script_runner

   pub global activate script_runner
   

2. 配置 pubspec.yaml 或 script_runner.yaml

   在 pubspec.yaml 中添加以下内容：

   script_runner:
     scripts:
       - build: flutter build apk
       - test: flutter test
       - format: dart format lib/
       - analyze: dart analyze
       - deploy: build && test && flutter pub publish
   

3. 运行脚本

   使用 scr 命令运行脚本：

   scr build
   scr test
   scr format
   scr analyze
   scr deploy
   

4. 查看帮助

   查看所有可用脚本的帮助信息：

   scr -h
   

通过以上步骤，你可以轻松地在 Flutter 项目中集成 script_runner，从而简化日常开发任务的执行。希望这对你有所帮助！

如果你有任何问题或需要进一步的帮助，请随时提问！