包术语词汇表

以下术语用于 包管理 和 pub 工具 的文档中。

包含程序或应用程序的包，具有 主入口点。旨在直接运行，无论是在命令行还是在浏览器中。

应用程序包可能具有对其他包的 依赖项，但从不依赖于自身。与常规的 包 不同，它们并非旨在共享。

应用程序包应该将它们的 锁文件 检查到源代码管理中，以便所有参与应用程序开发的人员以及应用程序部署的所有位置都具有一致的依赖项集。由于它们的依赖项受锁文件约束，应用程序包通常为其依赖项的 版本约束 指定 any。

pub.dev 存储库维护其托管的每个包版本的 sha256 哈希。Pub 客户端可以使用此哈希来验证下载的包的完整性，并防止存储库上的更改。

当 dart pub get 下载包时，它会计算下载的存档的哈希。每个托管依赖项的哈希与 解析 一起存储在 锁文件 中。

Pub 客户端使用此内容哈希来验证使用相同的锁文件（可能在不同的计算机上）再次运行 dart pub get 是否使用完全相同的包。

如果锁定的哈希与当前 pub 缓存中的哈希不匹配，pub 会重新下载存档。如果仍然不匹配，锁文件会更新并打印警告。例如

$ dart pub get
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
 ~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "pub.dev"
This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.
 
The content-hashes in pubspec.lock has been updated.

For more information see:
https://dart.ac.cn/go/content-hashes

Changed 1 dependency!

更新的内容哈希将显示在您的版本控制差异中，并应让您感到怀疑。

要将差异变为错误而不是警告，请使用 dart pub get --enforce-lockfile。如果它无法找到具有相同哈希的包存档，它会导致解析失败，而不会更新锁文件。

$ dart pub get --enforce-lockfile
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

For more information see:
https://dart.ac.cn/go/content-hashes
Would change 1 dependency.
Unable to satisfy `pubspec.yaml` using `pubspec.lock`.

To update `pubspec.lock` run `dart pub get` without
`--enforce-lockfile`.

您的包依赖的另一个包。如果您的包想要从其他包中导入代码，则该包必须是一个依赖项。依赖项在您包的 pubspec 中指定，并在 包依赖项 中描述。

要查看包使用的依赖项，请使用 pub deps。

在 Dart 的一般上下文中，入口点是一个由 Dart 实现直接调用的 Dart 库。当您在 <script> 标签中引用 Dart 库或将其作为命令行参数传递给独立 Dart VM 时，该库就是入口点。换句话说，它通常是包含 main() 的 .dart 文件。

在 pub 的上下文中，入口点包或根包是依赖项图的根。它通常是一个应用程序。当您运行应用程序时，它就是入口点包。它所依赖的每个其他包在该上下文中都不会是入口点。

包可以在某些上下文中是入口点，而在其他上下文中则不是。假设您的应用程序使用包 A。当您运行应用程序时，A 不是入口点包。但是，如果您转到 A 并执行其测试，则在该上下文中，它是入口点，因为您的应用程序没有参与其中。

包内的目录，允许包含 Dart 入口点。

Pub 有一系列这样的目录：benchmark、bin、example、test、tool 和 web（以及 Flutter 应用程序 的 lib）。这些目录（除了 bin）的任何子目录也可能包含入口点。

您的包直接使用的 依赖项。您在 pubspec 中列出的依赖项是您包的直接依赖项。所有其他依赖项都是 传递依赖项。

库是一个单独的编译单元，由一个单独的主文件和任何可选的 部分 组成。库有自己的私有范围。

名为 pubspec.lock 的文件，指定包依赖的每个直接和传递依赖项的具体版本和其他识别信息。

与仅列出直接依赖项并允许版本范围的 pubspec 不同，锁文件全面地将整个依赖项图固定到特定版本的包。锁文件确保您可以重新创建应用程序使用的包的精确配置。

当您运行 pub get、pub upgrade 或 pub downgrade 时，锁文件会由 pub 自动为您生成。Pub 包含每个包的 内容哈希，以便在将来的解析过程中进行检查。

如果您的包是 应用程序包，您通常会将它检入到源代码管理中。对于常规包，您通常不会。

一个目录下的 库 集合，该目录的根目录中包含一个 pubspec.yaml 文件。

包可以具有对其他包的 依赖项，并且本身也可以是依赖项。包的 /lib 目录包含其他包可以导入和使用的 公共库。它们还可以包含要直接运行的脚本。不打算被其他包依赖的包称为 应用程序包。共享包被 发布 到 pub.dev，但您也可以拥有未发布的包。

不要将包的 锁文件 检入到源代码管理中，因为库应该支持一系列依赖项版本。包的 直接依赖项 的 版本约束 应该尽可能宽泛，同时仍然确保依赖项与测试过的版本兼容。

由于 语义版本控制 要求库为任何向后不兼容的更改递增其主版本号，因此包通常需要其依赖项的版本大于或等于测试过的版本，小于下一个主版本。因此，如果您的库依赖于（虚构的）transmogrify 包，您在版本 1.2.1 上测试了它，您的版本约束将是 ^1.2.1。

包声明支持的 Dart SDK 本身的声明版本。SDK 约束使用正常的 版本约束 语法指定，但在 pubspec 中的特殊环境部分 中。

Pub 可以从中获取包的一种地方。源不是像 pub.dev 网站或某个特定 Git URL 那样具体的位置。每个源都描述了以某种方式访问包的一般过程。例如，git 是一个源。git 源知道如何根据 Git URL 下载包。有几个不同的 支持的源 可用。

当 pub 获取远程包时，它会将其下载到 pub 维护的单个系统缓存目录中。在 Mac 和 Linux 上，此目录默认为 ~/.pub-cache。在 Windows 上，此目录默认为 %LOCALAPPDATA%\Pub\Cache，但其确切位置可能会根据 Windows 版本而有所不同。您可以使用 PUB_CACHE 环境变量指定不同的位置。

一旦包在系统缓存中，pub 就会创建一个 `package_config.json` 文件，将您的应用程序使用的每个包映射到缓存中的相应包。

您只需要下载一次给定版本的包，然后就可以在任意多个包中重复使用它。如果您指定 `--offline` 标志以使用缓存的包，则可以在无需访问网络的情况下删除和重新生成您的 `package_config.json` 文件。

您的包间接使用的依赖项，因为它的一个依赖项需要它。如果您的包依赖于 A，而 A 又依赖于 B，B 又依赖于 C，那么 A 是 直接依赖项，而 B 和 C 则是传递依赖项。

拥有包管理权限的人员。包上传者可以上传包的新版本，他们还可以 添加和删除该包的其他上传者。

如果包有经过验证的发布者，则发布者的所有成员都可以上传该包。

拥有一个或多个包的用户组。每个经过验证的发布者都由一个经过验证的域名标识，例如 **dart.dev**。有关经过验证的发布者的常规信息，请参阅 经过验证的发布者页面。有关创建经过验证的发布者和将包迁移到其上的详细信息，请参阅 发布包 的文档。

对包的每个 依赖项 施加的约束，指定该包预期可以与哪些版本的依赖项一起使用。这可以是一个版本（`0.3.0`）或一个版本范围（`^1.2.1`）。虽然 `any` 也允许，但出于性能原因，我们不建议使用它。

有关更多信息，请参阅 版本约束。

包 应该始终为其所有依赖项指定版本约束。另一方面，应用程序包 通常应该允许其依赖项的任何版本，因为它们使用 锁定文件 来管理其依赖项版本。

有关更多信息，请参阅 Pub 版本化哲学。

除非另有说明，否则本网站上的文档反映了 Dart 3.5.3。页面最后更新时间为 2024-04-11。 查看源代码 或 报告问题。