包术语词汇表

以下术语用于包管理和 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 中一个特殊的 environment 部分。

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 版本控制哲学。

一组包的集合，它们与共享的依赖约束解决方案一起开发。在单体仓库（monorepo）中开发时非常有用。

这些包共享一个 pubspec.lock 和 .dart_tool/package_config.json。

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