发布 package

Pub package 管理工具 不但可以让你使用其他人开发的 package，而且能向全世界分享你自己制作的 package。如果你有一个有用的项目，且希望别人能够用到它，请使用 dart pub publish 命令。

观看下面的视频以了解构建和发布 package 的基本流程。

切记，发布过的 package 将会永久存在。只要你发布了你的 package，用户就能依赖它。而依赖关系一旦建立，移除 package 将破坏他们的项目。为了避免这种事发生，除了极少数情况， pub.dev 政策 不允许撤回已经发布的 package。

你可以一直上传 package 的新版本，但是旧版本对于那些尚未准备好升级的用户仍然可用。

对于那些已经发布，但不再相关或不再维护的 package，你可以 把他们标记为终止。

发布一个 package 时，请遵守 pubspec 格式 和 package 的文件结构 中的规范。为了简化 package 的使用，Dart 需要这些规范。这些规范中还存在一些例外的情况，详情请查阅这两个规范中的内容。当调用发布命令时，pub 会提示你可以做出的更改，以便帮助你的 package 在 Dart 生态系统中更好地展现。

除了这些规范以外，你还必须遵守以下要求：

• 你的 package 必须包含一个 LICENSE 文件。我们推荐 BSD 3-clause 许可证，也就是 Dart 和 Flutter 团队通常所使用的许可证。当然，你也可以使用任何适合你 package 的许可证。

• 对于你所上传的 package 任意部分，你必须拥有重新分发的合法权利。

• 通过 gzip 压缩后，你的 package 必须小于 100 MB。如果它所占空间过大，请考虑将它分割为多个小的 package，使用 .pubignore 移除不需要的文件，或者减少包含的资源或示例的数量。

• 让你的 package 仅依赖于来自默认的 pub package 服务托管的依赖项和属于 SDK 的依赖项（sdk: flutter）。这些限制条件确保了 package 的依赖项在未来依然可用。

• 你必须拥有一个 Google 账户， Pub 将使用 Google 账户来管理 package 的上传权限。你的 Google 账户可以与 Gmail 或其他任何邮箱地址关联。

Pub 在 pub.dev/packages/<your_package> 里，使用几个文件的内容来创建你的 package 页面。以下就是会影响到页面内容的几个文件。

README.md
该文件是你的 package 页面主要的组成部分。文件内容请使用 Markdown 标记语言进行编写。要了解如何编写出色的 README，请查阅 编写 package 页面。

CHANGELOG.md
如果你的 package 存在 CHANGELOG.md 文件，它就会作为页面的一个选项卡进行展示。开发者可通过 pub.dev 直接阅读它的内容。文件内容请使用 Markdown 标记语言进行编写。

pubspec.yaml
该文件用于完善你的 package 页面详细信息（包括描述、主页等），这些信息将被展现在页面的右侧。文件内容请遵守 YAML 的规范进行编写。

你可以使用已验证发布者（推荐）或一个独立的 Google 账户来发布 package。使用已验证发布者有以下几个优点：

• 你 package 的使用者知道发布者域名已经过验证。

• 你可以避免让 pub.dev 展示你的个人邮箱，pub.dev 将展示发布者域名和联系地址作为代替。

• 一个已验证发布者徽章 将在你的 package 名字旁边展示，不论是在搜索页面还是单独的 package 页面。

请按照以下步骤，来创建一个已验证发布者：

1. 访问 pub.dev。

2. 用一个 Google 账户登录 pub.dev。

3. 从右上角的用户菜单中，选择 创建发布者 (Create Publisher)。

4. 输入你想要与发布者关联的域名（例如，dart.dev）。

5. 点击 创建发布者 (Create Publisher)。

6. 在确认弹框中，选择 OK。

7. 如果出现提示，请在打开的 Google Search Console 中完成验证流程。

   • 添加 DNS 记录时， Search Console 可能需要几个小时才能响应更改。

   • 验证流程完成后，返回第 4 步。

使用 dart pub publish 命令来首次发布你的 package，或者将 package 升级到一个新版本。

在你 package 中的 所有文件 都会被包含在发布的 package 中，但是以下情况除外：

• 所有 隐藏 文件和文件夹——即文件名以 . 开头的文件。

• 在 .pubignore 和 .gitignore 文件中所列出的需要忽略的文件和目录。

如果你需要 git 和 dart pub publish 有不同的忽略规则，你可以创建 .pubignore 文件来对 .gitignore 进行重载。如果一个目录同时存在 .pubignore 和 .gitignore 文件，则 dart pub publish 不会采用 .gitignore 的规则。 .pubignore 文件的格式与 .gitignore 文件格式 相同。

如果你不想发布一些文件，请参考以下步骤：

• 删除它们，或者把它们添加到 .pubignore 或 .gitignore 文件内。

• 上传 package 时，请执行 dart pub publish --dry-run 来仔细检查文件列表。如果发现了不需要的文件，则取消这次上传。

为了测试 dart pub publish 命令会如何工作，你可以演示一次试运行（不会真的发布，只显示效果）：

$ dart pub publish --dry-run

通过该命令，dart pub 会执行以下流程：

1. 验证 package 是否符合 pubspec 格式 和 package 的文件结构 的规范。

2. 展示所有准备发布的文件。

以下示例展示了将要发布的名为 transmogrify 的 package：

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.

当你已经准备好发布你的 package 时，请移除 --dry-run 参数：

$ dart pub publish

With this command, dart pub performs the following tasks:

1. Verifies that your package follows the pubspec format and package layout conventions.

2. Shows all of the files it intends to publish.

3. Uploads your package to pub.dev.

在你的 package 成功上传至 pub.dev 之后，任何用户都能够下载或在项目中依赖它。

例如，如果你刚刚发布了你的 transmogrify package 1.0.0 版本，那么另一个 Dart 开发者将可以把它作为一项依赖添加到 pubspec.yaml 文件中：

dependencies:
  transmogrify: ^1.0.0

pub.dev 会检测 package 支持哪些平台，并呈现到 package 的页面上。用户可以过滤查找特定平台的 package。

若要改变生成的支持平台列表，则需要在 pubspec.yaml 文件中 指定平台。

Once you have published the first version of a package, you can configure automated publishing through GitHub Actions or Google Cloud service accounts. To learn more about automated publishing, consult Automated publishing of packages to pub.dev.

如果你正专注于开发一个 package，考虑将它以预发行的方式发布。预发行将在以下 任意情况下 下变得实用：

• 你正在活跃的开发该 package 的下一个主版本。

• 你想要为该 package 下一个候选的发布版做 beta 测试。

• 该 package 依赖于 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 版本。

当一个预发布被发布在 pub.dev，package 主页会同时展示预发布和稳定发布的链接。预发布不会影响分析评分，不会出现在搜索结果里，也不会代替 package 的 README.md 文件和说明文档。

在以下条件都满足时，发布预览版将会更有利：

• 下一个稳定版本是完整功能的版本。

• 在最新的稳定版 Dart SDK 中，没有发布目前版本使用的 API。

• 你的 package 所依赖的 API 或功能在发布到稳定版 SDK 前不会再改变。

举个例子，假设 package:args 的 2.0.0 版本是已经完成的版本，但它依赖了 Dart 3.0.0-417.1.beta 的功能，这时 3.0.0 的 SDK 尚未发布。它的 pubspec 如下：

name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

当这个 package 发布到 pub.dev 上时，会被标记为预览版，如下图所示， 1.6.0 是正式版而 2.0.0 是预览版。

当 3.0.0 稳定版的 Dart 发布后，pub.dev 会更新 package 列表，此时 2.0.0 会显示为最新（稳定）版本。

如果上面的所有条件都满足，那么你可以在运行 dart pub publish 时忽略以下的警告：

"Packages with an SDK constraint on a pre-release of the Dart SDK should themselves be published as a pre-release version. If this package needs Dart version 3.0.0-0, consider publishing the package as a pre-release instead."

如果 package 已经有了已验证发布者， pub.dev 页面将展示已验证发布者域名。

如果 package 的发布者没有选择认证，出于隐私原因，pub.dev 不会披露发布者的信息。 Publisher 会显示 "unverified uploader (未经验证的上传者)"。

发布 package 第一个版本的人将成为唯一有权对其进行版本更新的人。

要允许或取消其他人更新版本，可以从下列两种方法中任选一种：

• 在管理页面上管理授权的 package 上传者： https://pub.dev/packages/<package>/admin。

• 将 package 转给一个 已验证的发布者，这个发布者的所有成员都有上传的权利。

想要把 package 转移至已验证发布者，你必须是 package 的一个上传者，以及已验证发布者的管理员。

请根据以下步骤，将 package 转移至已验证发布者：

1. 用一个作为 package 上传者之一的 Google 账户登录 pub.dev。

2. 访问 package 详情页面（例如，https://pub-web.flutter-io.cn/packages/http）。

3. 选择 Admin 选项卡。

4. 输入已验证发布者的名称，然后点击 转移至已验证发布者 (Transfer to Publisher)。

如果你需要为了在 7 天内防止新 package 用户采用已发布的 package 版本，你可以在发布后 7 天内撤回该软件包版本。撤回的版本可以在撤回后的 7 天内再次恢复。

撤回并不是删除。 撤回的 package 版本会显示在 pub.dev 上版本列表的 Retracted versions 区域。同时，对应版本的详细信息内会有一个 RETRACTED 标签。

在撤回版本之前，你可以考虑直接发布一个新版本。撤回版本可能会对用户造成混乱和负面的使用体验。

如果你不小心发布了 未有效限制依赖版本 的新版本，那么撤回可能是唯一的选择。发布新版本对于这样的情况来说是无效的，因为 pub 依然能解析到新版。撤回未有效限制依赖版本的版本，可以让用户在尝试依赖时报错，或者升级到更新的版本。

然而，如果你的新版本仅仅是包含了一个小 bug，便无需撤回版本。发布一个修复了 bug 的新版，并且在 CHANGELOG.md 中标注内容，可以帮助用户了解到问题所在。发布新版也会让用户的使用体验更好。

如果一个 package 的对应版本已被撤回，在 pubspec.lock 标明它被依赖时仍然能被使用。如果你想依赖某个撤回的版本，你可以在 pubspec.yaml 文件中的 dependency_overrides 部分固定对应版本的使用。

When a package depends on a retracted package version, you have choices in how you migrate away from this version depending on other available versions.

In most cases a newer version has been published to replace the retracted version. In this case run dart pub upgrade <package>.

If no newer version is available, consider downgrading to the newest non-retracted version. You can do this in one of two ways.

1. Use pub tool commands:

   1. Run dart pub downgrade <package> to get the lowest version of the specified package that matches the constraints in the pubspec.yaml file.

   2. Run dart pub upgrade <package> to get the newest compatible and non-retracted version available.

2. Edit the pubspec.lock file in your preferred IDE:

   1. Delete the entire package entry for the package with the retracted version.

   2. Run dart pub get to get the newest compatible and non-retracted version available.

Though you could delete the pubspec.lock file and run dart pub get, this is not recommended. It might result in version changes for other dependencies.

If there is no alternative version available that satisfies the current version constraint, edit the version constraint in the pubspec.yaml file and run dart pub upgrade.

想要撤回或恢复 package 的某个版本，首先你需要使用 Google 账号登录到 pub.dev，该账号需要是该 package 的上传者或 认证的发布者 管理。接着进入到 package 页面上的 Admin 标签栏，进行撤回和恢复版本操作。

Although packages remain published, you can signal to developers that a package receives no active maintenance. This requires you to mark the package as discontinued.

Once you discontinue a package, the package will:

• Remain published on pub.dev.
• Remain viewable on pub.dev.
• Display a clear DISCONTINUED badge.
• Not appear in pub.dev search results.

To mark a package as discontinued:

1. Sign in to pub.dev using a Google Account with uploader or verified publisherpermissions for the package.

2. Navigate to the package's Admin tab.

3. To discontinue a package, select Mark "discontinued".

You can also recommend a replacement package.

1. In the field under Suggested replacement, type the name of another package.

2. Click Update "Suggested Replacement".

If you change your mind, you can remove the discontinued mark at any time.