如何使用套件

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 的範例，其中宣告了對兩個套件 (intl 和 path) 的相依性，這兩個套件都託管在 pub.dev 網站上

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 工作區 (單一程式碼庫支援)

• 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。 檢視來源 或 回報問題。