如何使用包

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.lang.tw/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.lang.tw/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。 檢視原始碼 或 報告問題.