Package 术语词汇表

以下术语用于 包管理 和 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 中特殊的 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 工作区。

除非另有说明，否则本网站上的文档反映的是 Dart 3.7.1 版本。页面上次更新于 2024-12-10。 查看源代码 或 报告问题。