自定义包仓库

dart pub 工具支持第三方包仓库。包仓库是托管 Dart 包的服务器，供 dart pub 工具使用。默认的包仓库 pub.dev 由 Dart 团队运营，旨在方便 Dart 包的公开发布。包仓库通过一个 hosted-url 标识，例如 https://dart-packages.example.com/。

有时，自定义包仓库可能对托管私有包很有用，包括以下一些场景：

1. 在组织内部共享专有包。
2. 在企业环境中严格控制依赖项。
3. 没有公共互联网访问权限的安全环境。

使用 git 依赖项来托管私有包也很常见，但是 dart pub 工具不支持针对 git 仓库解析版本；它只获取 git 仓库的特定修订版本。因此，当多人协作时，通常最好使用私有包仓库。

大多数自定义包仓库都是需要身份验证的私有包仓库。为了对自定义包仓库进行身份验证，dart pub 工具会在请求中附加一个密钥令牌。

你可以从自定义包仓库获取密钥令牌，并通过手动或环境变量方式指定它。要手动指定密钥令牌，请使用 dart pub token add 命令，该命令会提示你输入令牌：

dart pub token add https://dart-packages.example.com
Enter secret token: [enter secret token]
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token.

你还可以通过 --env-var 标志告诉 dart pub 从环境变量中读取令牌，包括在 CI 环境中：

dart pub token add https://dart-packages.example.com --env-var MY_SECRET_TOKEN
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token stored in the environment variable "MY_SECRET_TOKEN".

这确保了 dart pub 不会实际将密钥令牌存储在其配置中，而只是存储它应该从环境变量 $MY_SECRET_TOKEN 中读取密钥的事实。这降低了在 CI 作业之间共享执行环境时密钥意外泄露的风险。

要从自定义包仓库获取包，你必须在 pubspec.yaml 中使用 托管包的语法指定包的 hosted-url。例如：

dependencies:
  example_package:
    hosted: https://dart-packages.example.com
    version: ^1.4.0

在前面的示例中，package:example_package 从 https://dart-packages.example.com 获取。如果此包仓库需要身份验证，请参阅使用自定义包仓库进行身份验证，了解如何验证请求的更多信息。

你还可以使用 dart pub add 命令和 --hosted 标志从自定义包仓库添加依赖项：

dart pub add example_package --hosted https://dart-packages.example.com

你还可以从不同的包仓库获取不同的依赖项，因为可以为每个依赖项指定 hosted-url：

dependencies:
  # package retry is fetched from pub.dev (the default package repository)
  retry: ^3.0.0
  # package example_package is fetched from https://dart-packages.example.com
  example_package:
    hosted: https://dart-packages.example.com
    version: ^1.4.0

这使你可以在私有包仓库上保留私有包，同时使用最新的公共包作为依赖项。

然而，如果你的依赖项需要来自不同仓库的同名包，则很容易出现冲突。例如，如果包 retry 需要来自 pub.dev 的 meta，而 example_package 需要来自 https://dart-packages.example.com 的 meta。因此，如果将任何包镜像到私有包仓库中，通常需要镜像所有依赖项，并更新每个包的 dependencies 部分，或覆盖默认包仓库。

要将包发布到自定义包仓库而不是 pub.dev，请在 pubspec.yaml 中指定 publish_to 属性。如果启用了身份验证，发布将使用与检索包相同的令牌身份验证。

要准备将包发布到 https://dart-packages.example.com，你的 pubspec.yaml 应至少如下所示：

name: example_package
version: 1.0.0
# Ensures the package is published to https://dart-packages.example.com
publish_to: https://dart-packages.example.com

然后，要发布包的新版本，请使用 dart pub publish：

dart pub publish
Publishing example_package 1.0.0 to https://dart-packages.example.com
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- lib
|   '-- example_package.dart
'-- pubspec.yaml
...

默认情况下，除非使用托管依赖项语法指定自定义包仓库，否则 dart pub 会从 pub.dev 站点检索依赖项并发布包。但是，你可以使用 PUB_HOSTED_URL 环境变量覆盖默认包仓库。

这种方法在将所有包镜像到私有包仓库或在受限网络环境中工作时镜像 pub.dev 的子集时特别有用。

你可以通过实现托管 Pub 仓库规范版本 2中概述的 REST API 来编写自定义包仓库。

自定义包仓库也作为一种服务提供，并支持多个供应商的令牌身份验证，从而减轻了你托管和维护自己的自定义包仓库的开销：

• Cloudsmith
• Inedo ProGet
• JFrog Artifactory
• OnePub Dart Repository