如何使用包

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

如果您的包是一个 应用程序包，您应该将此文件检入 源代码控制。这样，每个在您的应用上工作的人都使用相同版本的全部依赖项。检入 lockfile 还确保您部署的应用使用相同版本的代码。

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

$ dart pub upgrade

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

$ 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 将警告您并更新 lockfile 以反映已发布版本。

例如，如果您手动更改 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 工作区（monorepo 支持）

• 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.7.1 版本。页面上次更新于 2024-12-11。 查看源代码 或 报告问题。