目录
description bug_report

发布 package

目录 keyboard_arrow_down keyboard_arrow_up
more_horiz

Pub package 管理工具 不但可以让你使用其他人开发的 package，而且能向全世界分享你自己制作的 package。如果你有一个有用的项目，且希望别人能够用到它，请使用 dart pub publish 命令。

观看下面的视频以了解构建和发布 package 的基本流程。

发布是永久的

切记，发布过的 package 将会永久存在。只要你发布了你的 package，用户就能依赖它。而依赖关系一旦建立，移除 package 将破坏他们的项目。为了避免这种事发生，除了极少数情况，pub.dev 政策 不允许撤回已经发布的 package。

你可以一直上传自己 package 的新版本，但是旧版本对于那些尚未准备好升级的用户仍然可用。

对于那些已经发布，但不再相关或不再维护的 package，你可以 把他们标记为终止。

准备发布

发布一个 package 时，遵守 pubspec 格式 和 package 布局惯例 很重要。为了其他人能使用你的 package，有些要求是必须的，其他则是一些有助于用户更好理解和使用的建议。对于以上两者，pub 都会指出具体的改变方法，帮助你的 package 在 Dart 生态系统中展现的更好。对于上传 package 有一些额外的要求：

  • 你的 package 必须包含一个 LICENSE 文件。我们推荐 BSD 3-clause 许可证，也就是 Dart 和 Flutter 团队所使用的开源许可证。同时，对于你所上传的 package 任意部分，你必须拥有重新发布的合法权利。

  • 通过 gzip 压缩后，你的 package 必须小于 100 MB。如果它所占空间过大，考虑将它分割为几个小的 package、使用 .pubignore 移除不需要的文件，或者减少包含资源或实例的数量。

  • 你的 package 应该仅依赖于已被托管的依赖项（来自默认的 pub 包服务）和属于 SDK 的依赖项（sdk: flutter）。这些限制条件确保了你的 package 的依赖项在未来依然可用。

  • 你必须有一个 Google 账户，pub 将使用它来管理 package 上传权限。你的 Google 账户可以与 Gmail 或其他任何邮箱地址关联。

重要的文件

Pub 在 pub.dev/packages/<your_package> 里，使用几个文件的内容来创建你的 package 页面。以下就是会影响到页面效果的几个文件：

  • README.md: README.md 文件是你 package 页面的主要组成部分。它的内容将会按 Markdown 格式渲染。

    想按照规范编写一个超棒的 README 吗，请参阅 编写 package 介绍页。

  • CHANGELOG.md: 如果你 package 的 CHANGELOG.md 文件存在，同样会作为页面的一个选项卡展示。开发者可通过 pub.dev 阅读它。它的内容将会按 Markdown 格式渲染。

  • The pubspec: 你 package 的 pubspec.yaml 文件被用于填写关于 package 本身的细节，例如它的描述，主页等等。这些信息将被展现在页面的右侧。

使用已验证发布者的优点

你可以使用已验证发布者（推荐）或一个独立的 Google 账户来发布 package。使用已验证发布者有以下几个优点：

  • 你 package 的使用者知道发布者域名已经过验证。

  • 你可以避免让 pub.dev 展示你的个人邮箱，pub.dev 将展示发布者域名和联系地址作为代替。

  • 一个已验证发布者徽章 pub.dev verified publisher logo 将在你的 package 名字旁边展示，不论是在搜索页面还是单独的 package 页面。

创建一个已验证发布者

想要创建一个已验证发布者，跟随以下步骤：

  1. 访问 pub.dev。

  2. 用一个 Google 账户登录 pub.dev。

  3. 在右上角的用户菜单中，选择 创建发布者。

  4. 输入你想要与发布者关联的域名（例如，dart.dev），然后点击 创建发布者。

  5. 在确认弹框中，选择 好。

  6. 如果收到提示，在打开的 Google 搜索控制台 中完成确认流程。

    • 添加 NDS 记录，可能需要几个小时让搜索控制台确认改动。

    • 确认流程完成后，返回第四步。

发布你的 package

使用 dart pub publish 命令来首次发布你的 package，或者把它升级到一个新版本。

演示一次试运行

为了测试 dart pub publish 命令会如何工作，你可以演示一次试运行（不会真的发布，只显示效果）：

$ dart pub publish --dry-run

Pub 会确认你的 package 符合 pubspec 格式 和 package 布局惯例，然后把它上传至 pub.dev。 Pub 也会提前向你展示所有准备发布的文件。如下是一个示例，展示了将要发布的名为 transmogrify 的 package：

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

发布

当你已经准备好发布你的 package 后，移除 --dry-run 参数：

$ dart pub publish

在你的 package 成功上传至 pub.dev 之后，任何用户都能够下载或在项目中依赖它。例如，如果你刚刚发布了你的 transmogrify package 1.0.0 版本，那么另一个 Dart 开发者将可以把它作为一项依赖添加到 pubspec.yaml 文件中：

dependencies:
  transmogrify: ^1.0.0

Automated publishing

Once the first version of a package has been published, it is possible to configure automated publishing through GitHub Actions or Google Cloud service accounts. To learn more about automated publishing, see Automated publishing of packages to pub.dev.

把 package 转移至已验证发布者

想要把 package 转移至已验证发布者，你必须是 package 的一个上传者，以及已验证发布者的管理员。

以下是如何把 package 转移至已验证发布者：

  1. 用一个作为 package 上传者之一的 Google 账户登录 pub.dev。

  2. 访问 package 详情页面（例如，https://pub.flutter-io.cn/packages/http）。

  3. 选择 管理员 选项卡。

  4. 输入已验证发布者的名称，然后点击 转移至已验证发布者。

哪些文件会被发布？

在你 package 中的 所有文件 都会被包含在发布的 package 中，除了以下几个例外：

  • 所有 隐藏 文件和文件夹——即文件名以 . 开头的文件

  • .pubignore 和 .gitignore 文件忽略的所有文件

如果你需要 git 和 dart pub publish 有不同的规则，你可以创建 .pubignore 对 .gitignore 进行重载。（如果一个文件夹既有 .pubignore 又有 .gitignore 文件，则 dart pub publish 不会采用 .gitignore 的规则） .pubignore 文件的格式与 .gitignore 文件格式 相同。

如果你不想发布一些文件，请参考以下步骤：

  • 删除它们，或者把它们加入 .pubignore 或 .gitignore 文件。

  • 执行 dart pub publish 上传前仔细检查文件列表。如果发现了不需要的文件，则取消这次上传。

平台支持

pub.dev 会检测 package 支持哪些平台，并呈现到 package 的页面上。用户可以过滤查找特定平台的 package。

若要改变自动检测生成的支持平台列表，则需要在 pubspec 文件中 指定平台。

上传者

发布 package 第一个版本的人，将自动成为唯一有权对其进行更新的人。

要允许或取消其他人更新版本，可以从下列两种方法中任选一种：

  • 管理页面管理授权的 package 上传者： https://pub.dev/packages/<package>/admin。

  • 将 package 转给一个 已验证的发布者，这个发布者的所有成员都有上传的权利。

发布者展示

如果 package 有了已验证发布者， pub.dev 页面将展示已验证发布者域名。

如果 package 的发布者没有选择认证，出于隐私原因，我们不会披露发布者的信息。 (Publisher 会显示 “unverified uploader”，即：未经验证的上传者)。

以预发行的方式发布

如果你正专注于开发一个 package，考虑将它以预发行的方式发布。预发行将在以下 任意情况下 下变得实用：

  • 你正在活跃的开发该 package 的下一个主版本。

  • 你想要为该 package 下一个候选的发布版做 beta 测试。

  • 该 package 依赖于 Dart 或 Flutter SDK 的一个不稳定版本。

正如在 版本号语义 中描述的那样，要制作一个版本的预发布，你需要为其添加一个后缀。例如，要给 2.0.0 版本做一个预发布，你可能会使用 2.0.0-dev.1 作为版本号。接下来，当你发布 2.0.0 正式版后，它将优先于所有诸如 2.0.0-XXX 的预发布。

当稳定发布版可用时，pub 会主动选择它们，所以使用预发布的用户可能需要改变它们的依赖约束。例如，如果一个用户想要测试 2.1 版本的预发布，那么他可能需要指明是 ^2.1.0-dev.1 版本，而不是 ^2.0.0 或者 ^2.1.0 版本。

当一个预发布被发布在 pub.dev，package 主页会同时展示预发布和稳定发布的链接。预发布不会影响分析评分，不会出现在搜索结果里，也不会代替 package 的 README.md 文件和说明文档。

发布预览版本

在以下条件都满足时，预览版是非常有用的版本：

  • 下一个稳定版本是完整功能的版本。

  • 在最新的稳定版 Dart SDK 中，没有发布目前版本使用的 API。

  • 你的 package 所依赖的 API 或功能在发布到稳定版 SDK 前不会再改变。

举个例子，假设 package:args 的 2.0.0 版本是已经完成的版本，但它依赖了 Dart 3.0.0-417.1.beta 的功能，这时 3.0.0 的 SDK 尚未发布。它的 pubspec 如下：

name: args
version: 2.0.0

environment:
  sdk: '>=3.0.0-417.1.beta <4.0.0'

当这个 package 发布到 pub.dev 上时，会被标记为预览版，如下图所示， 1.6.0 是正式版而 2.0.0 是预览版。

Illustration of a preview version

当 3.0.0 的稳定版 SDK 发布后，pub.dev 会更新 package 列表，此时 2.0.0 会显示为稳定版本。

如果上面的所有条件都满足，那么你可以在运行 dart pub publish 时忽略以下的警告：

“Packages with an SDK constraint on a pre-release of the Dart SDK should themselves be published as a pre-release version. If this package needs Dart version 3.0.0-0, consider publishing the package as a pre-release instead.”

撤回 package 的某个版本

出于某些特殊情况，若你需要一个新版本被用户使用，你可以在发布后 7 天内撤回该软件包版本。撤回的版本可以在撤回后的 7 天内再次恢复。

被撤回的版本不会被删除，它会显示在 pub.dev 上的 Retracted versions 区域。同时，对应版本的详细信息内会有一个 RETRACTED 标签。

在撤回版本之前，你可以考虑直接发布一个新版本。撤回版本可能会对用户造成混乱和负面的使用体验。

如果你不小心发布了 未有效限制依赖版本 的新版本，那么撤回可能是唯一的选择。发布新版本对于这样的情况来说是无效的，因为 pub 依然能解析到新版。撤回未有效限制依赖版本的版本，可以让用户在尝试依赖时报错，或者升级到更新的版本。

然而，如果你的新版本仅仅是包含了一个小 bug，便无需撤回版本。发布一个修复了 bug 的新版，并且在 CHANGELOG.md 中标注内容，可以帮助用户了解到问题所在。发布新版也会让用户的使用体验更好。

如何使用已撤回的版本

如果一个 package 的对应版本已被撤回，在 pubspec.lock 标明它被依赖时仍然能被使用。如果你想依赖某个撤回的版本，你可以在 pubspec.yaml 文件中的 dependency_overrides 部分固定对应版本的使用。

How to migrate away from a retracted package version

When a package depends on a package version that is retracted, there are different ways to migrate away from this version depending on what other versions are available.

Upgrade to a newer version

In most cases a newer version has been published to replace the retracted version. In this case run dart pub upgrade <package>.

Downgrade to the newest non-retracted version

If there is no newer version available, the best action might be to downgrade to the newest non-retracted version. There are two ways to get this version.

The first way is by using pub tool commands:

  1. Run dart pub downgrade <package> to get the lowest version of the specified package that matches the constraints in the pubspec.yaml file.
  2. Run dart pub upgrade <package> to get the newest compatible and non-retracted version available.

The second way is by editing the pubspec.lock file manually:

  1. Delete the entire package entry for the package with the retracted version.
  2. Run dart pub get to get the newest compatible and non-retracted version available.

It is also possible to completely delete the pubspec.lock file and then run dart pub get. However, this might also result in version changes for other dependencies.

Upgrade or downgrade to a version outside the specified version constraint

If there is no alternative version available that satisfies the current version constraint, edit the version constraint in the pubspec.yaml file and run dart pub upgrade.

如何撤回或恢复 package 的某个版本

想要撤回或恢复 package 的某个版本，首先你需要使用 Google 账号登录到 pub.dev，该账号需要是该 package 的上传者或 认证的发布者 管理。接着进入到 package 页面上的 Admin 标签栏，进行撤回和恢复版本操作。

把 package 标记为终止

尽管 package 的发布总是会被保留，在需要时，把它标记为不再活跃的维护将会对开发者有帮助。为了达到这一点，你可以将一个 package 标记为 终止。终止的 package 曾经的发布依然留存在 pub.dev 上，并可以被看到，但是它有一个清楚的 终止 徽章，而且不会出现在搜索结果中。

要把 package 标记为终止，首先你需要使用 Google 账号登录到 pub.dev，该账号需要是该 package 的上传者或 认证的发布者 管理。接着进入到 package 页面上的 Admin 标签栏，在其中将其标记为终止。如果你回心转意想继续维护，可在任意时候移除终止标记。