內容

套件相依性

相依性是 pub 套件管理員 的核心概念之一。相依性 是您的套件運作所需的另一個套件。相依性會在您的 pubspec 中指定。您只會列出直接相依性:您的套件直接使用的軟體。Pub 會為您處理 傳遞相依性

此頁面包含有關如何指定相依性的詳細資訊。最後面會列出 套件相依性的最佳實務

概觀

#

對於每個相依性,您會指定您所依賴的套件的名稱,以及您允許的該套件的版本範圍。您也可以指定 來源。來源會告訴 pub 如何找到套件。

舉例來說,您可以使用下列格式指定相依性

yaml
dependencies:
  transmogrify: ^1.0.0

此 YAML 程式碼會使用預設套件儲存庫 (pub.dev) 建立對 transmogrify 套件的相依性,並允許從 1.0.02.0.0 的任何版本(但不包含 2.0.0)。若要了解此語法,請查看 版本限制

若要指定 pub.dev 以外的來源,請使用 sdkhostedgitpath。例如,下列 YAML 程式碼會使用 path 告訴 pub 從本機目錄取得 transmogrify

yaml
dependencies:
  transmogrify:
    path: /Users/me/transmogrify

下一節會說明每個相依性來源的格式。

相依來源

#

Pub 可以使用下列來源找到套件

已主機套件

#

已主機的 套件是可以從 pub.dev 網站(或其他使用相同 API 的 HTTP 伺服器)下載的套件。以下是宣告對已主機套件的相依性的範例

yaml
dependencies:
  transmogrify: ^1.4.0

此範例指定您的套件會依賴名為 transmogrify 的已主機套件,並會使用從 1.4.0 到 2.0.0 的任何版本(但不包含 2.0.0 本身)。

如果您想要使用自己的 套件儲存庫,您可以使用 hosted 來指定其 URL。下列 YAML 程式碼會使用 hosted 來源建立對 transmogrify 套件的相依性

yaml
environment:
  sdk: '>=2.15.0 < 3.0.0'

dependencies:
  transmogrify:
    hosted: https://some-package-server.com
    version: ^1.4.0

版本限制是選填的,但建議使用。如果沒有提供版本限制,系統會假設為 any

Git 套件

#

有時您會處於領先地位,需要使用尚未正式發布的套件。也許您的套件本身仍在開發中,並且正在使用同時開發的其他套件。為了讓這更容易,您可以直接依賴儲存在 Git 儲存庫中的套件。

yaml
dependencies:
  kittens:
    git: https://github.com/munificent/kittens.git

這裡的 git 表示此套件是使用 Git 找到的,而其後的網址是可用于複製套件的 Git 網址。

即使套件儲存庫是私有的,如果您能 使用 SSH 連接到儲存庫,那麼您可以使用儲存庫的 SSH 網址來依賴套件

yaml
dependencies:
  kittens:
    git: [email protected]:munificent/kittens.git

如果您想依賴特定的提交、分支或標籤,請在描述中新增 ref

yaml
dependencies:
  kittens:
    git:
      url: [email protected]:munificent/kittens.git
      ref: some-branch

ref 可以是 Git 允許用來 識別提交 的任何內容。

Pub 假設套件位於 Git 儲存庫的根目錄中。若要指定儲存庫中的不同位置,請指定相對於儲存庫根目錄的 path

yaml
dependencies:
  kittens:
    git:
      url: [email protected]:munificent/cats.git
      path: path/to/kittens

路徑相對於 Git 儲存庫的根目錄。

Git 依賴項不被允許作為上傳到 pub.dev 的套件的依賴項。

路徑套件

#

有時您會發現自己同時處理多個相關套件。也許您在建立使用它的應用程式的同時,正在建立一個架構。在這些情況下,在開發過程中,您真的希望依賴本地檔案系統上該套件的即時版本。這樣,一個套件中的變更會立即被依賴它的套件接收。

為了處理這個問題,pub 支援路徑依賴項

yaml
dependencies:
  transmogrify:
    path: /Users/me/transmogrify

這表示 transmogrify 的根目錄是 /Users/me/transmogrify。對於此依賴項,pub 會直接產生指向所參考套件目錄的 lib 目錄的符號連結。您對依賴套件所做的任何變更都會立即看到。您不需要在每次變更依賴套件時執行 pub。

允許使用相對路徑,並且會視為相對於包含您的 pubspec 的目錄。

路徑依賴項對於本地開發很有用,但在與外界共用程式碼時無法使用,因為並非所有人都能存取您的檔案系統。因此,如果您在 pubspec 中有任何路徑依賴項,您就無法將套件上傳到 pub.dev 網站

相反,典型的流程是

  1. 在本地編輯您的 pubspec 以使用路徑依賴項。
  2. 處理主套件和它所依賴的套件。
  3. 一旦它們都正常運作,請發布依賴套件。
  4. 變更您的 pubspec 以指向其依賴項目前已託管的版本。
  5. 如果您願意,也可以發佈您的主要套件。

SDK

#

SDK 原始碼用於與套件一起發佈的任何 SDK,這些 SDK 本身可能是依賴項。目前,Flutter 是唯一受支援的 SDK。

語法如下所示

yaml
dependencies:
  flutter_driver:
    sdk: flutter

sdk: 之後的識別碼表示套件來自哪個 SDK。如果是 flutter,只要

  • Pub 在 flutter 可執行檔的內容中執行
  • Flutter SDK 包含具有給定名稱的套件

如果是未知識別碼,則依賴項始終被視為未滿足。

版本限制

#

假設您的套件 A 依賴於套件 B。您如何向其他開發人員傳達哪個版本的套件 B 與給定版本的套件 A 相容?

若要讓開發人員知道版本相容性,請指定版本約束。您希望允許最廣泛的版本範圍,以提供您的套件使用者靈活性。範圍應排除無法運作或尚未測試的版本。

Dart 社群使用語意版本1

您可以使用傳統語法插入符號語法來表達版本約束。兩種語法都指定相容版本的範圍。

傳統語法提供明確的範圍,例如 '>=1.2.3 <2.0.0'。插入符號語法提供明確的起始版本 ^1.2.3

yaml
environment:
  # This package must use a 2.x version of the Dart SDK starting with 2.14.
  sdk: '>=2.14.0 < 3.0.0'

dependencies:
  transmogrify:
    hosted:
      name: transmogrify
      url: https://some-package-server.com
    # This package must use a 1.x version of transmogrify starting with 1.4.
    version: ^1.4.0

若要進一步瞭解 pub 的版本系統,請參閱 套件版本化頁面

傳統語法

#

使用傳統語法的版本約束可以使用下列任何值

允許使用?備註
任何所有版本作為明確宣告空版本約束的用途。
1.2.3僅給定版本由於對使用您的套件的應用程式施加額外限制,因此會限制套件的採用。
>=1.2.3給定版本或更新版本
>1.2.3較給定版本更新的版本
<=1.2.3給定版本或舊版本
<1.2.3較給定版本早的版本當您知道一個較高版本與您的套件相容時使用此功能。此版本可能是第一個引入重大變更的版本。

您可以指定任何版本值的組合,因為它們的範圍會相交。例如,如果您將版本值設定為 '>=1.2.3 <2.0.0',這會結合這兩個限制,因此相依性可以是從 1.2.32.0.0 的任何版本,但不包括 2.0.0 本身。

插入符號語法

#

插入符號語法以簡潔的方式表達版本限制。^version 表示保證與給定版本向後相容的所有版本範圍。此範圍將包含所有版本,直到下一個版本引入重大變更。由於 Dart 使用語意版本控制,因此對於任何 1.0 或更新版本的套件版本,這將是下一個主要版本;對於任何早於 1.0 的套件版本,這將是下一個次要版本。

版本值範圍涵蓋至插入符號語法傳統語法
>=1.0下一個主要版本^1.3.0'>=1.3.0 <2.0.0'
<1.0下一個次要版本^0.1.2'>=0.1.2 <0.2.0'

以下範例顯示插入符號語法

yaml
dependencies:
  # Covers all versions from 1.3.0 to 1.y.z, not including 2.0.0
  path: ^1.3.0
  # Covers all versions from 1.1.0 to 1.y.z, not including 2.0.0
  collection: ^1.1.0
  # Covers all versions from 0.1.2 to 0.1.z, not including 0.2.0
  string_scanner: ^0.1.2

開發相依

#

Pub 支援兩種相依性:一般相依性和開發相依性。開發相依性與一般相依性的不同之處在於您所依賴的套件的開發相依性會被忽略。以下是一個範例

假設 transmogrify 套件在其測試中使用 test 套件,且僅在其測試中使用。如果有人只想使用 transmogrify(匯入其函式庫),它實際上不需要 test。在此情況下,它將 test 指定為開發相依性。其 pubspec 會包含類似以下內容

yaml
dev_dependencies:
  test: '>=0.5.0 <0.12.0'

Pub 會取得您的套件所依賴的每個套件,以及那些套件所依賴的所有內容,並遞迴取得。它也會取得您的套件的開發相依性,但它會忽略任何相依套件的開發相依性。Pub 只會取得您的套件的開發相依性。因此,當您的套件依賴於 transmogrify 時,它會取得 transmogrify,但不會取得 test

決定一般相依性或開發相依性的規則很簡單:如果相依性是由 libbin 目錄中的某個項目匯入,則它需要是一般相依性。如果它僅由 testexample 等匯入,則它可以且應該是一個開發相依性。

使用開發相依性可以縮小相依性圖。這會讓 pub 執行得更快,並更容易找到一組滿足所有限制的套件版本。

相依覆寫

#

您可以使用 dependency_overrides 暫時覆寫對相依性的所有參照。

例如,您可能正在更新已發佈套件 transmogrify 的本地副本。Transmogrify 由依賴關係圖中的其他套件使用,但您不想複製每個套件到本地並變更每個 pubspec 以測試您本地的 transmogrify 副本。

在這種情況下,您可以使用 dependency_overrides 覆寫依賴關係,以指定包含套件本地副本的目錄。

pubspec 會看起來像以下內容

yaml
name: my_app
dependencies:
  transmogrify: ^1.2.0
dependency_overrides:
  transmogrify:
    path: ../transmogrify_patch/

當您執行 dart pub getdart pub upgrade 時,pubspec 的鎖定檔會更新,以反映到您的依賴關係的新路徑,而且無論在何處使用 transmogrify,pub 都會使用本地版本。

您也可以使用 dependency_overrides 指定套件的特定版本

yaml
name: my_app
dependencies:
  transmogrify: ^1.2.0
dependency_overrides:
  transmogrify: '3.2.1'

只有套件自己的 pubspec 中的依賴關係覆寫會在套件解析期間考量。忽略任何依賴套件中的依賴關係覆寫。

因此,如果您將套件發佈到 pub.dev,請記住您的套件的依賴關係覆寫會被您的套件的所有使用者忽略。

最佳實務

#

主動管理您的依賴關係。盡可能確保您的套件依賴於最新版本的套件。如果您的套件依賴於過時的套件,該過時套件可能會在其依賴關係樹中依賴於其他過時套件。過時的套件版本可能會對您應用程式的穩定性、效能和品質產生負面影響。

我們建議套件依賴關係的最佳做法如下。

使用插入符號語法

#

使用 插入符號語法 指定依賴關係。這允許 pub 工具在有新版本可用時選擇較新的套件版本。此外,它對允許的版本設定上限。

相依於最新穩定套件版本

#

使用 dart pub upgrade 更新到您的 pubspec 允許的最新套件版本。若要找出應用程式或套件中未在最新穩定版本上的依賴關係,請使用 dart pub outdated

收緊開發相依的版本限制

#

開發依賴關係定義您僅在開發時需要的套件。完成的應用程式不需要這些套件。這些套件的範例包括測試或程式碼產生工具。將 dev_dependencies 中套件的版本限制設定為您套件依賴的最新版本的下限。

收緊開發依賴項目的版本限制可能類似以下範例

yaml
dev_dependencies:
  build_runner: ^2.4.8
  lints: ^2.1.1
  test: ^1.25.1

此 YAML 將 dev_dependencies 設定為最新修補程式版本。

更新套件相依時務必測試

#

如果您執行 dart pub upgrade 而未更新 pubspec,API 應保持不變,您的程式碼應像以前一樣執行,但請測試以確保無誤。如果您修改 pubspec 並更新至新的主要版本,則可能會遇到重大變更,因此您需要更徹底地測試。

驗證已下載套件的完整性

#

擷取新依賴項時,請使用 --enforce-lockfile 選項,以確保提取的套件內容與原始檔案的內容相符。在不修改 鎖定檔案 的情況下,此旗標僅在下列情況下解析新依賴項:

  • pubspec.yaml 已滿足
  • pubspec.lock 未遺失
  • 套件的 內容雜湊 相符