内容

发布包

内容 keyboard_arrow_down keyboard_arrow_up
more_horiz

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

观看以下视频，概述构建和发布包。


如何在 Dart 中构建包

记住：发布是永久性的

#

请记住，已发布的包会永久存在。一旦您发布了您的包，用户就可以依赖它。一旦他们开始依赖它，删除该包就会破坏他们的项目。为避免这种情况，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 进行标记。要了解如何编写出色的自述文件，请参阅 编写包页面。
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 文件中列出要忽略的文件和目录

要为git和dart 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 的自动发布。

发布预发布版本

#

在处理软件包时，请考虑将其发布为预发布版本。预发布版本在以下情况下很有用

  • 您正在积极开发软件包的下一个主要版本。
  • 您希望为软件包的下一个候选版本寻找测试人员。
  • 该软件包依赖于 Dart 或 Flutter SDK 的不稳定版本。

如语义版本控制中所述，要创建版本的预发布版本，请在版本号后附加后缀。例如，要创建版本2.0.0的预发布版本，您可以使用版本2.0.0-dev.1。稍后，当您发布版本2.0.0时，它将优先于所有2.0.0-XXX预发布版本。

由于 pub 优先选择稳定的版本（如果可用），因此预发布软件包的用户可能需要更改其依赖项约束。例如，如果用户想要测试版本2.1.0的预发布版本，则他们可能会指定^2.1.0-dev.1，而不是^2.0.0或^2.1.0。

当您将预发布版本发布到 pub.dev 时，软件包页面会显示指向预发布版本和稳定版本的链接。预发布版本不会影响分析分数、出现在搜索结果中或替换软件包的README.md和文档。

发布预览版本

#

预览在以下所有条件都为真的情况下很有用

  • 软件包的下一个稳定版本已完成。
  • 该软件包版本依赖于 Dart SDK 中尚未在 Dart SDK 的稳定版本中发布的 API 或功能。
  • 您知道软件包依赖的 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 可以选择的唯一版本。撤回具有不正确依赖项约束的软件包版本会强制用户升级其他依赖项或导致依赖项冲突。

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

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

#

如果软件包依赖于后来被撤回的软件包版本，则只要该版本存在于依赖软件包的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. 点击**更新“建议的替换”**。

如果您改变主意，可以随时删除已停止维护的标记。

除非另有说明，本网站上的文档反映的是 Dart 3.5.3 版本。页面上次更新于 2024-10-22。 查看源代码 或 报告问题.