programming

发布包

Tue Jun 30, 2020

Publishing packages

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

注意: 如果要发布到 pub.dev 以外的其他位置，或者要防止在任何地方发布，请使用 pubspec 中定义的 publish_to 字段。

发布是永远的 #

请记住，发布是永远的。只要你发布你的包，用户就可以依赖它。一旦他们开始这样做，删除包就会破坏他们的包。为了避免这种情况，pub.dev 政策不允许取消发布软件包，除非是极少数情况。

你可以随时上传你的包的新版本，但旧的包将继续为那些还没有准备好升级的用户提供服务。

对于已经发布的包，如果不再相关或正在维护，你可以将其标记为停止发布。

准备发布 #

当发布一个软件包时，遵循 pubspec 格式和包布局惯例是很重要的。其中有些是必须的，以便其他人能够使用你的软件包。另一些则是为了帮助用户更容易理解和使用您的软件包而提出的建议。在这两种情况下，pub 都会尝试帮助你，指出哪些改变会帮助你的软件包在 Dart 生态系统中发挥得更好。上传包有一些额外的要求:

你必须包含一个包含开源许可证的 LICENSE 文件。我们推荐 BSD 许可证，这是 Dart 自己使用的。你也必须有合法的权利来重新发布你上传的任何东西作为你的包的一部分。
你的软件包在经过 gzip 压缩后必须小于 10 MB。如果太大，可以考虑将其分割成多个包，或者减少包含的资源或例子的数量。
你的包应该只依赖托管的依赖项(来自默认的 pub 包服务器)和 SDK 依赖项(sdk: flutter)。这些限制确保了你的包的依赖性不会在未来变得不可用。
您必须有一个 Google 帐户，pub 用来管理包的上传权限。您的 Google 账户可以与 Gmail 地址或任何其他电子邮件地址关联。

注意：除非您使用已验证的发布者发布，否则 pub.dev 会显示与您的 Google 帐户关联的电子邮件地址。

重要文件 #

Pub 使用一些文件的内容为你的包创建一个页面，地址是 pub.dev/packages/<your_package>。以下是影响你的包的页面外观的文件。

README.md: README.md 文件是你的包页面中的主要内容。该文件的内容以 Markdown 的形式呈现。
CHANGELOG.md：CHANGELOG.md 文件是你的包页面中的主要内容。你的包的 CHANGELOG.md 文件，如果找到的话，也会在你的包页面的一个标签中显示，这样开发者就可以直接从 pub.dev 中读取它。该文件的内容会以 Markdown 的形式呈现。
pubspec: 你的包的 pubspec.yaml 文件用来在你的包的页面右侧填写关于你的包的详细信息，比如它的描述、主页等。

使用经过验证的发布者的优势 #

您可以使用已验证的发布者（推荐）或独立的谷歌账户发布软件包。使用经过验证的发布者有以下优势。

您的包的消费者知道发布者的域名已经被验证。
您可以避免让 pub.dev 显示您的个人电子邮件地址。取而代之的是，pub.dev会显示发布者的域名和联系地址。
经验证的发布者徽章 pub.dev 经验证的发布者标识会在搜索页面和单个软件包页面上显示在您的软件包名称旁边。

创建一个验证过的发布者 #

要创建一个已验证的发布者，请按照以下步骤进行。

进入 pub.dev。
使用 Google 账户登录 pub.dev。
在右上角的用户菜单中，选择创建发布者。
输入您要与您的发布者相关联的域名(例如，dart.dev)，然后单击"创建发布者"。
在确认对话框中，选择"确定"。
如果提示，完成验证流程，这将打开 Google 搜索控制台。

在添加 DNS 记录时，可能需要几个小时后，搜索控制台才会反映出变化。
验证流程完成后，返回步骤4。

发布你的包 #

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

执行 dry run #

为了测试 pub publish 的工作情况，你可以进行一次 dry run:

$ pub publish --dry-run

Pub 会确保你的软件包遵循 pubspec 格式和包布局约定，然后将你的软件包上传到 pub.dev。Pub 还会向你展示它打算发布的所有文件。下面是一个发布名为 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.

发布 #

当你准备好发布你的包时，请删除 --dry-run 参数:

$ pub publish

注意: pub 命令目前不支持直接将新软件包发布到已验证的发布者。作为一个临时的变通方法，可以将新的软件包发布到Google账户，然后将包转移到发布者。

一旦软件包被转移到发布者，你就可以使用 pub publish 更新软件包。

当你的包成功上传到 pub.dev 后，任何 pub 用户都可以下载它或在他们的项目中依赖它。例如，如果你刚刚发布了 1.0.0 版本的 transmogrify 包，那么另一个 Dart 开发者可以在他们的 pubspec.yaml 中添加它作为依赖:

dependencies:
  transmogrify: ^1.0.0

将软件包传输给已验证的发布者 #

要将一个软件包转移到已验证的发布者，您必须是该软件包的上传者和已验证发布者的管理员。

注意：这个过程是不可逆的。一旦你将一个软件包转移到一个发布者，你不能将它转移回个人账户。

以下是如何将软件包转移到已验证的发布者:

用一个被列为软件包上传者的 Google 账户登录到 pub.dev。
进入软件包的详细信息页面(例如，https://pub.dev/packages/http)。
选择"管理"选项卡。
输入发布者的名称，然后单击"传输到发布者"。

哪些文件会被发布？ #

您的软件包中的所有文件都包含在已发布的软件包中，但有以下例外:

任何包的目录。
您的软件包的 lockfile 文件。
如果你没有使用 Git，所有隐藏的文件（也就是名字以 . 开头的文件）。
如果使用 Git，则是所有被 .gitignore 文件忽略的文件。

请确保删除任何你不想包含的文件(或将它们添加到 .gitignore 中)。 pub publish 在上传你的包之前列出了它要发布的所有文件，所以在完成上传之前要仔细检查列表。

上传者 #

谁发布了软件包的第一个版本，谁就会自动成为第一个也是唯一一个被授权上传该软件包其他版本的人。要允许或不允许其他人上传版本，请使用 pub uploader 命令或将软件包转移到已验证的发布者那里。

如果一个软件包有一个经过验证的发布者，那么该软件包的 pub.dev 页面会显示发布者的域名。否则，该页面将显示该软件包的授权上传者的电子邮件地址。

发布预发包 #

当你在做一个包的时候，考虑把它作为一个预发布。当以下任何一种情况发生时，预发布都是有用的。

你正在积极开发软件包的下一个主要版本。
你想为软件包的下一个发行候选版本招募测试者。
该包依赖于 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。

注意: 如果依赖关系图中的稳定包依赖于一个 prerelease，那么 pub 会选择那个 prerelease 而不是稳定版本。

当一个 prerelease 被发布到 pub.dev 时，软件包页面会同时显示到 prerelease 和稳定版的链接。prerelease 不会影响分析得分，不会出现在搜索结果中，也不会替换包的 README.md 和文档。

将软件包标记为已停产的软件包 #

尽管软件包总是保持发布，但向开发者发出信号，表明一个软件包不再被积极维护，是很有用的。为此，您可以将一个软件包标记为 discontinued。一个已停用的软件包仍然可以在 pub.dev 上发布和查看，但它有一个清晰的 DISCONTINUED 徽章，并且不会出现在 pub.dev 的搜索结果中。

要将软件包标记为已停用，请使用该软件包的上传者或已验证的发布者管理员的 Google 帐户登录 pub.dev。然后使用单个软件包的管理选项卡将该软件包标记为已停用。

资源 #

有关更多信息，请参见以下 pub 命令的参考页面。