如何使用包

Dart 生态系统使用包来管理共享软件，例如库和工具。要获取 Dart 包，您可以使用pub 包管理器。您可以在 pub.dev 网站 上找到公开可用的包，或者您可以从本地文件系统或其他地方加载包，例如 Git 存储库。无论您的包来自哪里，pub 都管理版本依赖项，帮助您获取与彼此和您的 SDK 版本兼容的包版本。

大多数 支持 Dart 的 IDE 提供对使用 pub 的支持，包括创建、下载、更新和发布包。或者，您可以在命令行上使用 dart pub。

至少，Dart 包是一个包含 pubspec 文件 的目录。pubspec 包含有关该包的一些元数据。此外，包可以包含依赖项（在 pubspec 中列出）、Dart 库、应用程序、资源、测试、图像和示例。

要使用包，请执行以下操作

• 创建一个 pubspec（一个名为 pubspec.yaml 的文件，其中列出了包依赖项，并包含其他元数据，例如版本号）。
• 使用 dart pub get 获取您的包的依赖项。
• 如果您的 Dart 代码依赖于包中的库，则导入该库。

pubspec 是一个名为 pubspec.yaml 的文件，位于应用程序的顶层目录中。最简单的 pubspec 只列出了包名

name: my_app

以下是一个 pubspec 示例，它声明了对两个托管在 pub.dev 网站上的包（js 和 intl）的依赖项

name: my_app

dependencies:
  js: ^0.6.0
  intl: ^0.17.0

要更新 pubspec.yaml 文件，无需手动编辑，您可以运行 dart pub add 命令。以下示例添加了对 vector_math 的依赖项。

$ 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 命令确定您的应用程序依赖于哪些包，并将它们放到一个中心 系统缓存 中。如果您的应用程序依赖于已发布的包，pub 会从 pub.dev 网站 下载该包。对于 Git 依赖项，pub 会克隆 Git 存储库。传递依赖项也会包含在内。例如，如果 js 包依赖于 test 包，pub 会同时获取 js 包和 test 包。

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

要导入包中找到的库，请使用 package: 前缀

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

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

您也可以使用此样式从自己的包中导入库。假设 transmogrify 包的布局如下

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

parser_test.dart 文件可以像这样导入 parser.dart

import 'package:transmogrify/parser.dart';

第一次获取包的新依赖项时，pub 会下载与其其他依赖项兼容的最新版本。然后，它通过创建一个锁定文件来锁定您的包，以始终使用该版本。这是一个名为 pubspec.lock 的文件，pub 会创建它并将其存储在您的 pubspec 旁边。它列出了您的包使用的每个依赖项（直接和传递）的特定版本。

如果您的包是 应用程序包，您应该将此文件检入 源代码控制。这样，每个人在使用您的应用程序时都会使用其所有依赖项的相同版本。检入锁定文件还可以确保您的已部署应用程序使用相同版本的代码。

当您准备好将依赖项升级到最新版本时，请使用 dart pub upgrade 命令

$ dart pub upgrade

dart pub upgrade 命令告诉 pub 重新生成锁定文件，使用包依赖项的最新可用版本。如果您只想升级一个依赖项，您可以指定要升级的包

$ dart pub upgrade transmogrify

该命令将 transmogrify 升级到最新版本，但保持其他所有内容不变。

由于 pubspec 中存在冲突的版本约束，dart pub upgrade 命令并不总是能够将每个包升级到其最新版本。要识别需要编辑 pubspec 的过时包，请使用 dart pub outdated。

在某些情况下，dart pub get 不会检索 pubspec.lock 文件中锁定的确切包版本

• 如果在最后更新 pubspec.lock 文件后，在 pubspec.yaml 中添加了新的依赖项或删除了依赖项。
• 如果锁定版本不再存在于包存储库中。
• 如果您更改了 Dart SDK 的不同版本，并且某些包不再与该新版本兼容。

在这些情况下，dart pub get 将

• 解锁足够的锁定依赖项版本，以使解析成为可能。
• 通知您与现有 pubspec.lock 相比的任何依赖项更改。

例如，在将 retry: ^3.0.0 添加到您的依赖项之后

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

此外，如果已发布的包版本的 内容哈希 与 pubspec.lock 文件中的哈希不同，pub 会警告您并更新锁定文件以反映已发布的版本。

例如，如果您手动更改 pubspec.lock 中 retry 的哈希值

$ 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.ac.cn/go/content-hashes
Changed 1 dependency!

将项目部署到生产环境时，请使用 dart pub get --enforce-lockfile 获取依赖项。

如果项目的依赖项约束无法使用 pubspec.lock 中的确切版本和内容哈希值满足，则包检索和命令将失败。这有助于避免将未经测试的依赖项和依赖项版本部署到生产环境。

$ 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.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`.

以下页面包含有关包和 pub 包管理器的更多信息。

• 创建包
• 发布包

• Pub 依赖项
• Pub 环境变量
• Pub 词汇表
• Pub 包布局约定
• Pub 版本控制理念
• Pubspec 格式

dart pub 工具提供以下子命令

• add
• cache
• deps
• downgrade
• get
• global
• outdated
• publish
• remove
• token
• unpack
• upgrade

有关所有 dart pub 子命令的概述，请参阅 pub 工具文档。

Pub 故障排除 提供了使用 pub 时可能遇到的问题的解决方案。

除非另有说明，本网站上的文档反映了 Dart 3.5.3。页面最后更新时间为 2024-10-03。 查看源代码 或 报告问题.