内容

以下术语用于 包管理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:
http://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:
http://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 有一个这些目录的列表:benchmarkbinexampletesttoolweb(以及 lib,用于 Flutter 应用程序)。这些目录的任何子目录(bin 除外)也可能包含入口点。

直接依赖项

#

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

#

一个库是一个单一的编译单元,由一个单一的主文件和任意数量的可选 部分 组成。库有自己的私有作用域。

锁定文件

#

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

与 pubspec 不同,pubspec 只列出直接依赖项并允许版本范围,而锁定文件将整个依赖关系图全面固定到软件包的特定版本。锁定文件确保你可以重新创建应用程序使用的软件包的确切配置。

当你运行 pub getpub upgradepub downgrade 时,pub 会自动为你生成锁定文件。Pub 为每个软件包包含一个 内容哈希,以便在未来的解析中进行检查。

如果你的软件包是 应用程序软件包,你通常会将其检入源代码管理。对于常规软件包,你通常不会这样做。

#

一个目录下的 集合,该目录的根目录中有一个 pubspec.yaml

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

不要将包的 lockfile 检入源代码管理,因为库应该支持一系列依赖项版本。包的 直接依赖项版本约束 应尽可能宽泛,同时仍确保依赖项与已针对其进行测试的版本兼容。

由于 语义版本控制 要求库对任何向后不兼容的更改增加其主要版本号,因此包通常要求其依赖项的版本大于或等于已测试的版本,并且小于下一个主要版本。因此,如果你的库依赖于(虚构的)transmogrify 包,并且你在版本 1.2.1 中对其进行了测试,那么你的版本约束将是 ^1.2.1

SDK 约束

#

包声明其支持的 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 又依赖于依赖于 C 的 B,那么 A 是直接依赖项,而 B 和 C 是传递依赖项。

上传者

#

对软件包具有管理权限的人员。软件包上传者可以上传软件包的新版本,他们还可以为该软件包添加和删除其他上传者

如果软件包具有经过验证的发布者,则发布者中的所有成员都可以上传该软件包。

已验证发布者

#

拥有软件包集的一个或多个用户。每个经过验证的发布者都由经过验证的域名标识,例如 dart.dev。有关经过验证的发布者的常规信息,请参阅经过验证的发布者页面。有关创建经过验证的发布者并向其传输软件包的详细信息,请参阅发布软件包的文档。

版本约束

#

对软件包的每个依赖项施加的约束,指定软件包预期的该依赖项的版本。这可以是单个版本(0.3.0)或一系列版本(^1.2.1)。虽然也允许使用 any,但出于性能原因,我们不建议使用它。

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

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

有关更多信息,请参阅Pub 版本控制理念