包术语表

以下术语用于包管理和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（以及 lib，用于Flutter 应用）。这些目录的任何子目录（除了 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 版本控制理念。

一起开发的软件包集合，其依赖项约束具有共享的解析。适用于在单代码仓库中进行开发。

这些软件包具有共享的 pubspec.lock 和 .dart_tool/package_config.json。

要了解有关在工作区中设置和开发的更多信息，请查看Pub 工作区。

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