内容

发布软件包

pub 包管理器不仅仅用于使用其他人的包。它还允许您与全世界共享您的包。如果您有一个有用的项目,并且希望其他人能够使用它,请使用 dart pub publish 命令。

观看以下视频,了解构建和发布包的概述。

记住:发布是永久的

#

请记住,已发布的包会永久存在。一旦您发布包,用户就可以依赖它。一旦他们开始依赖它,删除该包就会破坏他们的包。为了避免这种情况,pub.dev 政策 禁止取消发布包,除非极少数情况。

您始终可以上传包的新版本,但旧版本仍可供尚未升级的用户使用。

对于已失去相关性或缺乏维护的已发布包,将其标记为已停用

准备发布您的软件包

#

发布包时,请遵循 pubspec 格式包布局 结构中找到的约定。为了简化包的使用,Dart 需要这些约定。这些约定包含链接指南中指出的某些例外。调用时,pub 会指出您可以进行哪些更改,以便您的包在 Dart 生态系统中更好地工作。

除了这些约定之外,您还必须遵循以下要求

  • 在你的软件包中包含一个 LICENSE 文件。我们推荐使用 BSD 3 条款许可证,Dart 和 Flutter 团队通常使用此许可证。但是,你可以使用任何适合你软件包的许可证。

  • 验证你拥有合法权利来重新分发作为软件包一部分上传的任何内容。

  • 在 gzip 压缩后保持软件包大小小于 100 MB。如果软件包太大,请考虑将其拆分为多个软件包,使用 .pubignore 文件删除不必要的内容,或减少包含的资源或示例数量。

  • 让你的软件包仅依赖于默认 pub 软件包服务器和 SDK 依赖项(sdk: flutter)中的托管依赖项。这些限制确保将来可以找到并访问软件包的依赖项。

  • 拥有一个 Google 帐号。Pub 使用 Google 帐号来管理软件包上传权限。你的 Google 帐号可以与 Gmail 地址或任何其他电子邮件地址相关联。

填充您的 pub.dev 网页

#

Pub 使用几个文件的内容在 pub.dev/packages/<your_package> 中为你的软件包创建一个页面。以下文件会影响软件包网页的内容。

README.md
此文件包含软件包网页中的主要内容。文件的内容应使用 Markdown 标记。要了解如何编写出色的 README,请参阅 编写软件包页面
CHANGELOG.md
如果找到此文件,它会在软件包网页上填充自己的标签页。开发者可以直接从 pub.dev 阅读你的更改。文件的内容应使用 Markdown 标记。
pubspec.yaml
此文件填充软件包网页右侧有关软件包的详细信息。文件的内容应遵循 YAML 约定。这些详细信息包括描述、主页等。

使用已验证发布者的优势

#

你可以使用经过验证的发行商(推荐)或独立的 Google 帐号发布软件包。使用经过验证的发行商具有以下优势

  • 软件包的使用者知道发行商域已得到验证。
  • 你可以避免让 pub.dev 显示你的个人电子邮件地址。相反,pub.dev 会显示发行商域和联系地址。
  • pub.dev 网站在搜索页面和各个软件包页面上,在您的软件包名称旁边显示已验证发布者的徽章 pub.dev 已验证发布者徽标

创建已验证发布者

#

要创建 已验证发布者,请执行以下步骤

  1. 转到 pub.dev

  2. 使用 Google 帐号登录 pub.dev。

  3. 从右上角的用户菜单中,选择创建发布者

  4. 输入要与您的发布者关联的域名(例如,dart.dev)。

  5. 点击创建发布者

  6. 在确认对话框中,选择确定

  7. 如果出现提示,请完成验证流程。这会打开 Google Search Console

    • 在添加 DNS 记录时,Search Console 可能需要几个小时才能反映更改。
    • 当验证流程完成后,返回到步骤 4。

发布您的软件包

#

使用 dart pub publish 命令首次发布您的软件包或将其更新到新版本。

发布哪些文件?

#

已发布的软件包包括软件包根目录下的所有文件,但以下情况除外

  • 任何隐藏文件或目录。这些文件或目录的名称以点 (.) 开头。
  • .pubignore.gitignore 文件中列为要忽略的文件和目录

要对 gitdart pub publish 使用不同的忽略规则,请创建一个 .pubignore 文件以覆盖给定目录中的 .gitignore 文件。如果一个目录同时包含 .pubignore 文件和 .gitignore 文件,则 dart pub publish忽略该目录的 .gitignore 文件。.pubignore 文件遵循与 .gitignore 文件 相同的格式。

要避免发布不需要的文件,请遵循以下做法

  • 删除您不想包括的任何文件,或将它们添加到 .pubignore.gitignore 文件中。
  • 上传软件包时,检查 dart pub publish --dry-run 显示的将要发布的文件列表。如果该列表中出现任何不需要的文件,请取消上传。

测试发布您的软件包

#

要测试 dart pub publish 的工作方式,可以执行一次空运行

$ dart pub publish --dry-run

使用此命令,dart pub 执行以下任务

  1. 验证您的软件包是否遵循 pubspec 格式软件包布局约定

  2. 显示其打算发布的所有文件。

以下示例显示了发布名为 transmogrify 的软件包

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.

发布到 pub.dev

#

软件包准备就绪后,要发布软件包,请移除 --dry-run 参数

$ dart pub publish

使用此命令,dart pub 执行以下任务

  1. 验证您的软件包是否遵循 pubspec 格式软件包布局约定

  2. 显示其打算发布的所有文件。

  3. 将您的软件包上传到 pub.dev

您的软件包成功上传到 pub.dev 后,任何 pub 用户都可以下载它或在他们的项目中依赖它。

例如,如果您刚刚发布了 transmogrify 软件包的 1.0.0 版本,那么其他 Dart 开发人员可以在其 pubspec.yaml 中将其添加为依赖项

yaml
dependencies:
  transmogrify: ^1.0.0

检测支持的平台

#

pub.dev 网站 检测软件包支持哪些平台,并在软件包页面上显示这些平台。pub.dev 用户可以按平台过滤搜索。

要更改生成的支持平台列表,请在 pubspec.yaml 文件中 指定支持的平台

自动化发布

#

发布软件包的第一个版本后,您可以通过 GitHub Actions 或 Google Cloud 服务帐号配置自动发布。要详细了解自动发布,请参阅 在 pub.dev 上自动发布软件包

发布预发行版

#

在处理软件包时,请考虑将其发布为预发布版本。当满足以下任何条件时,预发布版本可能很有用

  • 您正在积极开发软件包的下一个主要版本。
  • 您需要为软件包的下一个候选版本寻找 beta 测试人员。
  • 该软件包依赖于不稳定的 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 时,软件包页面会显示指向预发布版本和稳定版本这两个版本的链接。预发布版本不会影响分析分数,不会出现在搜索结果中,也不会替换软件包 README.md 和文档。

发布预览版

#

在以下所有条件都为真时,预览版本很有用

  • 软件包的下一个稳定版本已完成。
  • 该软件包版本依赖于 Dart SDK 中的 API 或功能,而该 API 或功能尚未在 Dart SDK 的稳定版本中发布。
  • 您知道软件包所依赖的 API 或功能是 API 稳定的,并且在达到稳定 SDK 之前不会更改。

例如,考虑一个新版本的 package:args,它有一个已完成的版本 2.0.0。它依赖于 Dart 3.0.0-417.1.beta 中的一个功能。但是,Dart SDK 3.0.0 的稳定版本尚未发布。pubspec.yaml 文件可能如下所示

pubspec.yaml
yaml
name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

当您将此软件包发布到 pub.dev 时,它会被标记为预览版本。以下屏幕截图对此进行了说明。它将稳定版本列为 1.6.0,将预览版本列为 2.0.0

Illustration of a preview version

当 Dart 发布 3.0.0 的稳定版本时,pub.dev 会更新软件包列表,将 2.0.0 显示为该软件包的最新(稳定)版本。

如果本节开头的所有条件都为真,请忽略 dart pub publish 发出的以下警告

“对 Dart SDK 预发布版本的 SDK 约束的软件包本身应该发布为预发布版本。如果此软件包需要 Dart 版本 3.0.0-0,请考虑将软件包发布为预发布版本”。

管理发布权限

#

查找包发布者

#

如果某个软件包有已验证的发布者,则该软件包的 pub.dev 页面会显示发布者域名。

对于未经发布者发布的软件包,出于隐私原因,pub.dev 不会披露发布者。发布者字段显示“未验证的上传者”。

管理包上传者

#

第一个发布某个软件包版本的人将成为第一个且唯一有权上传该软件包的其他版本的授权人。

要允许或不允许其他人上传版本,请

  • 在软件包的管理页面上管理授权上传者:https://pub.dev/packages/<package>/admin
  • 将软件包转移给已验证的发布者;发布者的所有成员都有权上传。

将包转移到已验证的发布者

#

要将软件包转移给已验证的发布者,您必须是该软件包的上传者,并且是已验证发布者的管理员。

要将软件包转移给已验证的发布者

  1. 使用列为软件包上传者的 Google 帐户登录pub.dev

  2. 转到软件包详情页面(例如,https://pub.dev/packages/http)。

  3. 选择管理标签。

  4. 输入发布者的名称,然后点击转移给发布者

管理您的包

#

撤回包版本

#

要防止新的软件包使用者在七天内采用您软件包的已发布版本,您可以在发布后七天内撤回该软件包版本。撤回的版本可以在撤回后七天内再次恢复。

撤回不等于删除。已撤回的软件包版本会显示在 pub.dev 上软件包的版本列表中,位于已撤回版本部分。该软件包版本的详细视图会显示一个已撤回徽章。

在撤回软件包之前,请考虑发布新版本。撤回软件包可能会对软件包使用者产生负面影响。

如果您发布了一个具有缺少依赖项约束宽松依赖项约束的新版本,那么撤回软件包版本可能是唯一的解决方案。发布软件包的更新版本并不能阻止版本解析器选择旧版本。该版本可能是 pub 可以选择的唯一版本。撤回具有不正确依赖项约束的软件包版本会强制用户升级其他依赖项或获得依赖项冲突。

但是,如果你的软件包包含一个次要 bug,你可能不需要撤回该版本。发布一个已修复 bug 的新版本,并在 CHANGELOG.md 中描述已修复的 bug。这有助于用户了解发生了什么。发布新版本对软件包用户的影响较小。

如何使用已撤回的软件包版本

#

如果一个软件包依赖于一个稍后被撤回的软件包版本,只要该版本在依赖软件包的 pubspec.lock 文件中,它仍然可以使用该版本。要依赖于一个已撤回的特定版本,依赖软件包必须在 pubspec.yaml 文件的 dependency_overrides 部分固定该版本。

如何从已撤回的软件包版本迁移

#

当一个软件包依赖于一个已撤回的软件包版本时,你可以根据其他可用版本选择如何从该版本迁移。

升级到较新版本

#

在大多数情况下,已发布较新版本来替换已撤回版本。在这种情况下,运行 dart pub upgrade <package>

降级到最新的非撤回版本

#

如果没有较新版本可用,请考虑降级到最新的非撤回版本。你可以通过以下两种方式之一进行此操作。

  1. 使用 pub 工具 命令

    1. 运行 dart pub downgrade <package> 以获取与 pubspec.yaml 文件中的约束匹配的指定软件包的最低版本。

    2. 运行 dart pub upgrade <package> 以获取最新的兼容且未撤回的可用版本。

  2. 在首选的 IDE 中编辑 pubspec.lock 文件

    1. 删除带有已撤回版本的软件包的整个软件包条目。

    2. 运行 dart pub get 以获取最新的兼容且未撤回的可用版本。

虽然你可以删除 pubspec.lock 文件并运行 dart pub get,但这不推荐。它可能会导致其他依赖项的版本更改。

升级或降级到指定版本约束之外的版本

#

如果没有满足当前版本约束的替代版本可用,请编辑 pubspec.yaml 文件中的版本约束并运行 dart pub upgrade

如何撤回或恢复软件包版本

#

要撤回或恢复软件包版本,请首先使用 Google 帐号登录 pub.dev,该帐号是该软件包的上传者或 经过验证的发布者 管理员。然后转到该软件包的管理标签,你可以在其中撤回或恢复最近的软件包版本。

停用包

#

尽管软件包仍已发布,但你可以向开发者发出信号,表明该软件包没有收到积极的维护。这要求你将该软件包标记为已停用

一旦你停用一个软件包,该软件包将

  • 继续在 pub.dev 上发布。
  • 继续在 pub.dev 上显示。
  • 显示清晰的已停用徽章。
  • 不显示在 pub.dev 搜索结果中。

将软件包标记为已停用

  1. 使用具有上传者或已验证发布者权限的 Google 帐号登录 pub.dev。

  2. 导航到软件包的管理标签页。

  3. 要停用软件包,请选择标记为“已停用”

您还可以推荐替换软件包。

  1. 建议的替换下的字段中,键入另一个软件包的名称。

  2. 点击更新“建议的替换”

如果您改变主意,可以随时移除已停用标记。