如何使用包

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 站点上托管的两个包（intl 和 path）的依赖关系

name: my_app

dependencies:
  intl: ^0.20.0
  path: ^1.9.1

要更新 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 包布局约定
• Pub 版本控制理念
• Pubspec 格式

dart pub 工具提供了以下子命令：

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

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

排查 pub 问题提供了您在使用 pub 时可能遇到的问题的解决方案。

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