如何使用包

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.dev/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.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 包管理器的更多信息。

• 创建包
• 发布包
• 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.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.