如何使用套件

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.dev.org.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.dev.org.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 工作區 (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。 檢視原始碼 或 回報問題。