目录

发布包

目录 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/<你的包> 创建一个页面。以下文件会影响你的包网页的内容。

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. 验证 git status 是否干净。如果 git 中跟踪的文件有未提交的更改，则会发出警告。

  3. 显示它打算发布的所有文件。

  4. 将你的包上传到 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 。

预览版本的图示 {:width="600px"}

当 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.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.