Flutter 工具 - 手把手教你开发一个 Library Package

在日常工作中，我们会经常用到别人发布的 Packages，那你有没有想过发布属于自己的 Package 呢？如果您对本话题感兴趣，不妨继续读下去，本篇文章将会手把手教您发布属于自己的 Package。

---

一、创建 Package

若要创建一个新的 package，可以使用 dart create 命令，并加入 package 作为命令参数来创建。

dart create 命令支持使用多个模板之一创建一个 Dart 项目。

模板	描述
console	命令行应用程序。
package	包含共享 Dart 库的包。
server-shelf	使用shelf构建的服务器。
web	使用核心 Dart 库构建的 Web 应用程序。

本例我们使用 console模板来创建一个命令行应用程序。

dart create -t console <PACKAGE_NAME>

至此，一个简单的命令行应用程序经创建完毕。

---

二、调试 Package

下面我们在项目中编写一些简单的代码，然后进行本地调试。由于下面需要用到 args 和 io 这两个 package ，下面我们首先通过命令行来进行添加 dependencies。

dart pub add args
dart pub add io

代码目录结构如下图所示：

test_package/lib/src/commands/add_command.dart 文件中代码如下：

import 'dart:async';
import 'dart:io';

import 'package:args/command_runner.dart';
import 'package:io/io.dart';

class AddCommand extends Command<int> {
  /// constructor
  AddCommand() {
    argParser.addOption('width', help: 'Size of the width');
    argParser.addOption('height', help: 'Size of the height');
  }

  @override
  String get description => 'test add';

  @override
  String get name => 'add';

  int add(int width, int height) {
    return width + height;
  }

  @override
  Future<int> run() async {
    final int width = int.parse(argResults!['width']);
    final int height = int.parse(argResults!['height']);
    final int result = add(width, height);
    stdout.writeln('result====> $result');
    return ExitCode.success.code;
  }
}

test_package/lib/src/runner.dart 中代码如下：

import 'package:args/args.dart';
import 'package:args/command_runner.dart';
import 'package:io/io.dart';

import './commands/add_command.dart';

class TestCommandRunner extends CommandRunner<int> {
  /// constructor
  TestCommandRunner()
      : super(
          'test_package',
          'test add',
        ) {
    addCommand(AddCommand());
  }

  @override
  Future<int> run(Iterable<String> args) async {
    final ArgResults argResults = parse(args);
    final int exitCode = await runCommand(argResults) ?? ExitCode.success.code;
    return exitCode;
  }
}

test_package/bin/test_package.dart 中代码如下：

import 'dart:io';

import 'package:test_package/test_package.dart';

void main(List<String> arguments) async {
  exit(await TestCommandRunner().run(arguments));
}

代码已经编写完毕了，由于代码比较简单，就不再做过多解释，此时我们就需要用到 dart pub global 命令进行本地调试了。

Pub 的 global 选项允许你在任意位置下从命令行运行 Dart 脚本。在 激活 Package 后，你可以 运行 该 Package bin 目录下的脚本。 停用 Package 后你可以从全局可用的 Package 列表中将其移除。

• Package 激活：

  dart pub global activate [--noexecutables] [--executable=<name>] [--overwrite] <package> [version-constraint]
  

• 激活 pub.dev 网站上的 Package

  dart pub global activate <pub.dev package>
  

• 激活 Git 仓库中的 Package

  dart pub global activate --source git <Git URL>
  dart pub global activate -sgit <Git URL>
  

  使用 --source git（或 -sgit 简写）命令参数可以激活位于 Git 仓库中的 Package。下面的两个示例都可以用于激活位于 GitHub 网站上名为 async_await 的 Package。

• 激活当前设备上的 Package

  dart pub global activate --source path <path>
  

接下来我们激活当前设备上的 Package，来进行本地调试，我们首先执行以下命令：

dart pub global activate --source path ~/Desktop/test_package

激活成功后，命令行显示如下图：

此时执行以下命令便可以进行本地调试了：

test_package add --width=10 --height=20

然而，当我们执行完后，发现并不像我们想象中的一样，如下图所示：

提示已经很明确了，告诉我们找不到命令，经过查阅资料发现，我们需要在 pubspec.yaml 添加如下代码：

executables:
  test_package: test_package

上面代码的意思就是将一个或多个脚本公开为可直接从命令行运行的可执行文件。

此时我们再次激活当前设备上的 Package，然后再次执行 test_package add --width=10 --height=20命令，结果如下图所示：

到此为止我们本地调试 Package 已经完成，如果需要发布到 Pub 上，还是需要做做一些额外工作的，比如：编写测试用例、README 文件、CHANGELOG 文件等等，这里就不再进行赘诉，大家可以自行研究下。

---

三、手动发布到 Pub

发布 Package 需要以下四个步骤：

1. 准备一个可以发布包的账号（推荐使用认证账号），如果您还没有账号可以点击 Creating a verified publisher 来进行创建；

2. 通过执行 dart pub publish --dry-run 进行发布前校验，下面我们在刚刚创建的项目中进行下验证；如图所示：

   

   此时，命令行信息提示我们在项目根目录下需要一个 LICENSE 文件，以及在 pubspec.yaml 需要填写 homepage 或者 repository。按照提示修改，然后继续执行此命令即可。

3. 发布 Package 我们只需要执行 dart pub publish 即可，如果是第一次发布，需要是在命令行交互完成的，主要是为了验证用户，它会生成响应的 token；有了这里的第一次发布，后续我们才可以使用类似 GitHub Action 来进行自动化发布，这一点要切记；由于以上是测试代码，我们看下 svg_to_font 第一次发包时的截图：

   

4. 将尚未发送到 pub.dev 的包从您的账户转移到经过验证的账户,如下图所示：

   

至此，您已经完成了手动发布 Package 的整个过程。

---

四、通过 GitHub Action 自动发布

如果每次都要手动发布 Package，大家是不是很麻烦？下面我们就一起来看下如何使用 GitHub Action 自动发布。

通过 GitHub Action 自动发布只需要一下 4 个步骤：

1. 添加 .github/workflows/publish.yml 到项目根目录，文件内容可以参考 1. 文件内容参考svg_to_font；

2. 获取PUB_ACCESS_TOKEN并PUB_REFRESH_TOKEN； 根据 Dart and Flutter Package Publisher的说法，您可能不知道怎么获取；

   查看 dart cli 的源码，以 macOS 为例，正确地址为 ~Library/Application Support/dart/pub-credentials.json

3. 配置 GitHub ACtions Secrets，地址：https://github.com/<REPLACE Your Repo>/settings/secrets/actions；

4. 以 svg_to_font 仓库为例，输入一个以字母“v”开头的标签，它就会自动发布了。

---

五、参考文献

• Creating packages
• Dart create
• pubspec executables
• Publishing packages
• Dart and Flutter Package Publisher
• GitHub Actions