包术语词汇表

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

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

应用包可能依赖于其他包 依赖项 ，但从不依赖自身。 与普通的 包 不同，它们并非旨在共享。

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

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

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

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

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

$ dart pub get
正在解析依赖项...
foo-1.0.0 的缓存版本哈希值错误 - 正在重新下载。
 ~ foo 1.0.0 (之前为 1.0.0)
pubspec.lock 中的现有内容哈希值与以下内容不匹配：
 * 来自 "pub.dev" 的 foo-1.0.0
这表示以下情况之一：
 * 自您创建 pubspec.lock 以来，服务器上的内容已更改。
 * pubspec.lock 已损坏。

pubspec.lock 中的内容哈希值已更新。

更多信息，请参阅：
https://dart.dev/go/content-hashes

已更改 1 个依赖项！

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

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

$ dart pub get --enforce-lockfile
正在解析依赖项...
foo-1.0.0 的缓存版本哈希值错误 - 正在重新下载。
~ foo 1.0.0 (之前为 1.0.0)
pubspec.lock 中的现有内容哈希值与以下内容不匹配：
 * 来自 "pub.dev" 的 foo-1.0.0

这表示以下情况之一：
 * 自您创建 pubspec.lock 以来，服务器上的内容已更改。
 * pubspec.lock 已损坏。

更多信息，请参阅：
https://dart.dev/go/content-hashes
将更改 1 个依赖项。
无法使用 `pubspec.lock` 满足 `pubspec.yaml` 。

要更新 `pubspec.lock` ，请在不使用 `--enforce-lockfile` 的情况下运行 `dart pub get` 。

您的包所依赖的另一个包。 如果您的包想要导入其他包中的代码，则该包必须是依赖项。 依赖项在您包的 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 版本控制理念 。

一起开发的包的集合，以及它们依赖项约束的共享解析。 对于在 monorepo 中进行开发非常有用。

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

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

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.