套件術語表

以下術語用於套件管理和 pub 工具的文件中。

包含程式或應用程式的套件，具有主要進入點。旨在直接執行，無論是在命令列還是在瀏覽器中。

應用程式套件可能具有其他套件的相依性，但永遠不會被其他套件相依。與常規套件不同，它們不打算被共享。

應用程式套件應將其鎖定檔簽入原始碼控制，以便每個在應用程式上工作的人員以及部署應用程式的每個位置都具有一致的相依性集合。由於它們的相依性受到鎖定檔的約束，應用程式套件通常為其相依性的版本約束指定 any。

pub.dev 儲存庫維護其託管的每個套件版本的 sha256 雜湊。Pub 用戶端可以使用此雜湊來驗證下載套件的完整性，並防止儲存庫上的變更。

當 dart pub get 下載套件時，它會計算下載封存檔的雜湊。每個託管相依性的雜湊都與 解析一起儲存在鎖定檔中。

pub 用戶端使用此內容雜湊來驗證再次使用相同的鎖定檔 (可能在不同的電腦上) 執行 dart pub get 是否使用完全相同的套件。

如果鎖定的雜湊與目前在 pub 快取中的內容不符，pub 會重新下載封存檔。如果仍然不符，鎖定檔會更新並印出警告。例如

$ dart pub get
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
 ~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "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。如果它找不到具有相同雜湊的套件封存檔，則會導致解析失敗，而不會更新鎖定檔。

$ dart pub get --enforce-lockfile
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "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`.

您的套件所依賴的另一個套件。如果您的套件想要從其他套件匯入程式碼，則該套件必須是相依性。相依性在您的套件的pubspec 中指定，並在套件相依性中描述。

若要查看套件使用的相依性，請使用 pub deps。

在 Dart 的一般上下文中，「進入點」是 Dart 函式庫，由 Dart 實作直接調用。當您在 <script> 標籤中引用 Dart 函式庫，或將其作為命令列引數傳遞給獨立的 Dart VM 時，該函式庫就是進入點。換句話說，它通常是包含 main() 的 .dart 檔案。

在 pub 的上下文中，「進入點套件」或「根套件」是相依性圖形的根目錄。它通常會是應用程式。當您執行您的應用程式時，它是進入點套件。它相依的每個其他套件在該上下文中都不是進入點。

套件在某些上下文中可以是進入點，而在其他上下文中則不是。假設您的應用程式使用套件 A。當您執行您的應用程式時，A 不是進入點套件。但是，如果您前往 A 並執行其測試，在該上下文中，它是進入點，因為您的應用程式未參與。

允許包含Dart 進入點的套件內目錄。

Pub 有這些目錄的清單：benchmark、bin、example、test、tool 和 web (以及 lib，適用於 Flutter 應用程式)。這些目錄的任何子目錄 (bin 除外) 也可能包含進入點。

您的套件直接使用的相依性。您在 pubspec 中列出的相依性是您套件的直接相依性。所有其他相依性都是遞移相依性。

函式庫是單一編譯單元，由單一主要檔案和任意數量的可選部分組成。函式庫有自己的私有範圍。

名為 pubspec.lock 的檔案，指定套件所依賴的每個直接和遞移相依性的具體版本和其他識別資訊。

與僅列出直接相依性並允許版本範圍的 pubspec 不同，鎖定檔全面地將整個相依性圖形釘選到特定版本的套件。鎖定檔確保您可以重新建立應用程式使用的套件的確切配置。

當您執行 pub get、pub upgrade 或 pub downgrade 時，pub 會自動為您產生鎖定檔。Pub 包含每個套件的內容雜湊，以便在未來的解析期間進行檢查。

如果您的套件是應用程式套件，您通常會將其簽入原始碼控制。對於常規套件，您通常不會這樣做。

目錄下的 函式庫集合，在該目錄的根目錄中具有 pubspec.yaml。

套件可以具有其他套件的相依性並且本身也可以是相依性。套件的 /lib 目錄包含其他套件可以匯入和使用的公共函式庫。它們也可以包含要直接執行的腳本。不打算被其他套件相依的套件是應用程式套件。共享套件發佈到 pub.dev，但您也可以擁有未發佈的套件。

不要將套件的鎖定檔簽入原始碼控制，因為函式庫應支援一系列相依性版本。套件的直接相依性的版本約束應盡可能廣泛，同時仍確保相依性將與針對其測試的版本相容。

由於 語義化版本控制要求函式庫針對任何向後不相容的變更遞增其主要版本號，因此套件通常會要求其相依性的版本大於或等於測試的版本，且小於下一個主要版本。因此，如果您的函式庫相依於 (虛構的) transmogrify 套件，並且您在版本 1.2.1 進行了測試，則您的版本約束將為 ^1.2.1。

套件宣告其支援的 Dart SDK 本身宣告的版本。SDK 約束使用正常的版本約束語法指定，但在 pubspec 中特殊的環境區段中指定。

pub 可以從中取得套件的一種位置類型。來源不是像 pub.dev 網站或某些特定 Git URL 這樣的特定位置。每個來源都描述了以某種方式存取套件的一般程序。例如，git 是一種來源。git 來源知道如何下載給定 Git URL 的套件。有幾種不同的支援的來源可用。

當 pub 取得遠端套件時，它會將其下載到 pub 維護的單一系統快取目錄中。在 Mac 和 Linux 上，此目錄預設為 ~/.pub-cache。在 Windows 上，目錄預設為 %LOCALAPPDATA%\Pub\Cache，但其確切位置可能會因 Windows 版本而異。您可以使用 PUB_CACHE 環境變數指定不同的位置。

一旦套件位於系統快取中，pub 就會建立 package_config.json 檔案，將您的應用程式使用的每個套件對應到快取中的相應套件。

您只需下載給定版本的套件一次，然後就可以在您想要的任意多個套件中重複使用它。如果您指定 --offline 標記以使用快取的套件，您可以刪除並重新產生您的 package_config.json 檔案，而無需存取網路。

您的套件間接使用的相依性，因為其相依性之一需要它。如果您的套件相依於 A，而 A 又相依於 B，B 又相依於 C，則 A 是直接相依性，而 B 和 C 是遞移相依性。

對套件具有管理員權限的人員。套件上傳者可以上傳套件的新版本，他們也可以為該套件新增和移除其他上傳者。

如果套件具有已驗證的發佈者，則發佈者的所有成員都可以上傳套件。

擁有一組套件的一個或多個使用者。每個已驗證的發佈者都由已驗證的網域名稱識別，例如 dart.dev。有關已驗證發佈者的常規資訊，請參閱已驗證的發佈者頁面。有關建立已驗證的發佈者並將套件轉移到其中的詳細資訊，請參閱 發佈套件的文件。

對套件的每個相依性放置的約束，指定套件預期可與該相依性的哪些版本一起使用。這可以是單一版本 (0.3.0) 或版本範圍 (^1.2.1)。雖然也允許 any，但基於效能考量，我們不建議使用它。

如需更多資訊，請參閱版本約束。

套件應始終為其所有相依性指定版本約束。另一方面，應用程式套件通常應允許其相依性的任何版本，因為它們使用鎖定檔來管理其相依性版本。

如需更多資訊，請參閱Pub 版本控制哲學。

與其相依性約束的共享解析一起開發的套件集合。適用於在 monorepo 中開發。

這些套件具有共享的 pubspec.lock 和 .dart_tool/package_config.json。

若要深入了解如何在工作區中設定和開發，請查看Pub 工作區。

除非另有說明，否則本網站上的文件反映 Dart 3.7.1。頁面上次更新於 2024-12-10。 檢視原始碼 或 回報問題。