包術語詞彙表

以下術語用於包管理和 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.lang.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.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`.

你的包所依賴的另一個包。如果你的包要從其他包匯入程式碼，那麼該包必須是一個依賴項。依賴項在你的包的 pubspec 中指定，並在包依賴項中描述。

要檢視包使用的依賴項，請使用pub deps。

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

在 pub 的上下文中，入口點包或根包是依賴圖的根。它通常是一個應用程式。當你執行你的應用程式時，它就是入口點包。它所依賴的所有其他包在該上下文中都不是入口點。

一個包在某些上下文中可以是入口點，而在其他上下文中則不是。假設你的應用程式使用了包 A。當你執行應用程式時，A 不是入口點包。但是，如果你轉到 A 並執行其測試，在該上下文中，它是入口點，因為你的應用程式沒有參與。

你的包內部允許包含Dart 入口點的目錄。

Pub 有這些目錄的列表：benchmark、bin、example、test、tool 和 web（以及 Flutter 應用的 lib）。這些目錄的任何子目錄（除了 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 中一個特殊的 environment 部分。

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 工作區。