如何使用 package

目录 keyboard_arrow_down keyboard_arrow_up

创建 pubspec
获取包
从包中导入库
升级依赖
Get dependencies for production
更多内容

more_horiz

Dart 生态系统使用包来管理共享软件，比如：库和工具。我们使用 Pub 包管理工具 来获取 Dart 包。在 Pub 上，可以找到公开可用的包。或者从本地文件系统或其他的位置，比如 Git 仓库，加载可用的包。无论包是从什么途径加载的， Pub 都会进行版本依赖管理，从而帮助我们获得版本兼容的软件包以及 SDK 。

大多数 Dart-savvy IDEs 都支持 Pub 的使用，包括包的创建，下载，更新和发布。同样上述功能也可以在命令行上通过 dart pub 来操作。或者可以在命令行上使用pub。

Dart 包目录中至少包含一个 pubspec 文件。 pubspec 文件记录一些关于包的元数据。此外，包还包含其他依赖项（在 pubspec 中列出）， Dart 库，应用，资源，测试，图片，以及示例。

通过以下步骤，引用使用包：

创建一个 pubspec （一个名为 pubspec.yaml 文件，文件列出依赖的包以及包含的其他元数据，比如当前包的版本）。
使用 dart pub get 获取当前所依赖的包。
如果当前 Dart 代码依赖包中的某个库，导入 (import) 该库。

pubspec 是一个名为 pubspec.yaml 的文件，文件位于应用的根路径。最简单的 pubspec 只需要列出包名：

yaml

name: my_app

下面是一个 pubspec 的示例，示例中声明依赖了在 Pub 站点上托管的两个 package（js 和 intl）：

yamlname: my_app

dependencies:
  js: ^0.6.0
  intl: ^0.17.0

你可以使用 dart pub add 来操作 pubspec.yaml 文件，无需手动修改。下面的例子使用了命令来添加 vector_math package。

$ dart pub add vector_math
Resolving dependencies... 
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

有关创建 pubspec 的详细内容，请参阅 pubspec 文档以及使用包的相关文档。

项目中一旦拥有了 pubspec 文件，就可以在项目根目录中执行 dart pub get 命令：

$ cd <path-to-my_app>
$ dart pub get

上面的操作即 获取依赖。

dart pub get 命令确定当前应用所依赖的包，并将它们保存到中央系统缓存 (central system cache) 中。如果当前应用依赖了一个公开包， Pub 会从 Pub 站点获取该包。对于一个 Git 依赖， Pub 会 Clone 该 Git 仓库。同样包括包的相关依赖也会被下载。例如，如果 js 包依赖 test 包，pub 会同时获取 js 包和 test 包。

Pub 会创建一个 package_config.json 文件（位于 .dart_tool/ 目录下），该文件将应用程序所依赖的每个包名相应的映射到系统缓存中的包。

使用 package: 前缀，导入包中的库：

dartimport 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

Dart 运行时会抓取 package: 之后的内容，并在应用程序的 package_config.json 文件中查找它。

你也可以使用此方式从自己的 package 中导入库。比方说 transmogrify 这个 package 的结构如下：

transmogrify/
  lib/
    transmogrify.dart
    parser.dart
  test/
    parser/
      parser_test.dart

parser_test.dart 就可以通过下面的方式导入 parser.dart：

dart

import 'package:transmogrify/parser.dart';

第一次获取依赖时，Pub 会下载依赖及其兼容的最新版本。然后通过创建 lockfile 锁定依赖，以始终使用这个版本。 Pub 会在 pubspec 旁创建并存储一个名为 pubspec.lock 文件。它列出了使用的每个依赖包的指定版本（当前包或传递包的版本）。

如果包是一个应用程序包，那么应该将此文件加入到源文件管理。这样，在应用上开发的每个人都能够使用所有相同版本的包。同样加入到 lockfile 可以保证部署的应用使用的是同一版本的代码。

如果已经准备更新依赖到最新版本，使用 dart pub upgrade 命令：

$ dart pub upgrade

dart pub upgrade 命令用于重新生成 lockfile 文件，并使用最新可用版本的依赖包。如果仅升级某个依赖，可以在命令中指定需要升级的包：

$ dart pub upgrade transmogrify

上面的命令升级 transmogrify 到最新版本，但维持其它包不变。

dart pub upgrade 命令并非总是可以将所有的 package 更新到最新版本，原因是 pubspec 文件中的一些 package 之间有版本限制的冲突。想要确定 pubspec 里已经过时且需要编辑的 package，请使用 dart pub outdated 命令。

In some situations, dart pub get does not retrieve the exact package versions locked in the pubspec.lock file:

If new dependencies are added to or removed from pubspec.yaml after the pubspec.lock file was last updated.
If the locked version no longer exists in the package repository.
If you changed to a different version of the Dart SDK, and some packages are no longer compatible with that new version.

In these cases dart pub get will:

Unlock enough of the locked dependency versions that a resolution becomes possible.
Notify you about any dependency changes relative to the existing pubspec.lock.

For example, after adding retry: ^3.0.0 to your dependencies:

$ dart pub get
Resolving dependencies... (1.0s)
Downloading packages... 
+ retry 3.1.2

Also, if the content hash of a published package version differs from the hash in the pubspec.lock file, pub will warn you and update the lockfile to reflect the published version.

For example, if you manually change the hash of retry in pubspec.lock:

$ dart pub get
Resolving dependencies... 
Downloading packages... 
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://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.dev/go/content-hashes
Changed 1 dependency!

When deploying your project to production, use dart pub get --enforce-lockfile to retrieve dependencies.

If your project's dependency constraints can't be satisfied with the exact versions and content hashes in pubspec.lock, package retrieval and the command will fail. This helps avoid deploying untested dependencies and dependency versions to production.

$ dart pub get --enforce-lockfile
Resolving dependencies... 
Downloading packages... 
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://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.dev/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`.

以下链接的页面是关于包及 Pub 包管理的更多内容。

The dart pub tool provides the following subcommands:

有关所有 pub 命令的概述，参见 pub 工具文档。

Pub 故障排除提供使用中可能遇到问题的解决方法。

除非另有说明，文档之所提及适用于 Dart 3.5.4 版本，本页面最后更新时间: 2024-12-02。查看文档源码或者报告页面问题。

如何使用 package

创建 pubspec

获取包

从包中导入库

升级依赖

Get dependencies for production

更多内容

如何使用

参考

Pub 子命令

故障排除