目录

发布包

目录 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 进行标记。要了解如何编写出色的 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 文件中列出要忽略的文件和目录

要为 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。

发布预发布版本

#

当您开发包时，请考虑将其作为预发布版本发布。预发布版本在以下情况下可能很有用：

  • 您正在积极开发该包的下一个主要版本。
  • 您希望该包的下一个候选版本有 beta 测试人员。
  • 该包依赖于 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.6.0 版本。页面上次更新时间为 2024-12-06。 查看源代码 或 报告问题。