跳到主要内容
目录

发布软件包

目录 keyboard_arrow_down keyboard_arrow_up
更多

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 的以下警告

“SDK 约束在 Dart 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.7.1 版本。页面上次更新时间：2024-12-06。 查看源代码 或 报告问题。