目錄

套件術語詞彙表

下列術語用於 套件管理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:
http://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:
http://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 有這些目錄的清單:benchmarkbinexampletesttoolweb(以及 lib,適用於 Flutter 應用程式)。這些目錄的任何子目錄(bin 除外)也可能包含入口點。

直接相依性

#

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

函式庫

#

函式庫是一個單一編譯單元,由一個主要檔案和任何數量的選用 部分 組成。函式庫有自己的私人範圍。

鎖定檔

#

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

與 pubspec 不同,pubspec 只列出直接相依性並允許版本範圍,鎖定檔會將整個相依性圖形全面固定到特定版本的套件。鎖定檔可確保您可以重新建立應用程式所使用的套件的確切組態。

當您執行 pub getpub upgradepub downgrade 時,pub 會自動為您產生鎖定檔。Pub 會為每個套件包含 內容雜湊,以便在未來解析時進行比對。

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

套件

#

目錄下 程式庫 的集合,目錄根目錄中有一個 pubspec.yaml

套件可以對其他套件有 依賴關係而且本身也可以是依賴關係。套件的 /lib 目錄包含其他套件可以匯入和使用的 公開程式庫。它們也可以包含直接執行的指令碼。不打算讓其他套件依賴的套件就是 應用程式套件。共用套件會 發佈 到 pub.dev,但您也可以有未發佈的套件。

不要將套件的 鎖定檔 簽入原始碼控制,因為程式庫應該支援範圍的依賴關係版本。套件 直接依賴關係版本限制 應盡可能廣泛,同時仍確保依賴關係與測試過的版本相容。

由於 語意版本控制 要求程式庫在任何向後不相容的變更中增加其主要版本號碼,因此套件通常需要其依賴關係版本大於或等於測試過的版本,且小於下一個主要版本。因此,如果您的程式庫依賴(虛構的)transmogrify 套件,且您在版本 1.2.1 中測試過它,您的版本限制將會是 ^1.2.1

SDK 約束

#

套件宣告其支援的 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 版本控管原則