內容

每個 pub 套件 都需要一些元資料才能指定其 相依性。與他人共用的 pub 套件也需要提供一些其他資訊,以便使用者可以發現它們。所有這些元資料都會放入套件的 pubspec: 中,這是一個名為 pubspec.yaml 的檔案,使用 YAML 語言撰寫。

支援的欄位

#

pubspec 可以有下列欄位

name
每個套件都必須有。 進一步了解。
version
在 pub.dev 網站上託管的套件必須有。 進一步了解。
description
在 pub.dev 網站上託管的套件必須有。 進一步了解。
homepage
選用。指向套件首頁 (或原始碼存放庫) 的 URL。 進一步了解。
repository
選用。指向套件原始碼存放庫的 URL。 進一步了解。
issue_tracker
選用。指向套件問題追蹤器的 URL。 進一步了解。
documentation
選用。指向套件文件檔的 URL。 進一步了解。
dependencies
如果套件沒有相依性,可以省略。 進一步了解。
dev_dependencies
如果套件沒有開發相依性,可以省略。 進一步了解。
dependency_overrides
如果您不需要覆寫任何相依性,可以省略。 進一步了解。
environment
Dart 2 開始需要。 進一步了解。
executables
選用。用於將套件的可執行檔放在您的 PATH 中。 進一步了解。
platforms
選用。用於在 pub.dev 網站上明確宣告支援的平台。 進一步了解。
publish_to
選擇性。指定套件的發布位置。 深入了解。
funding
選擇性。使用者可以贊助套件開發的 URL 清單。 深入了解。
false_secrets
選擇性。執行發布前搜尋時,指定要忽略的檔案,以避免潛在的機密外洩。 深入了解。
screenshots
選擇性。指定要顯示在 pub.dev 網站 上的螢幕截圖檔案清單。 深入了解。
topics
選擇性。套件的主題清單。 深入了解。
ignored_advisories
選擇性。忽略的安全建議清單。 深入了解。

Pub 會忽略所有其他欄位。

如果您新增自訂欄位,請給予它一個獨特的名稱,以避免與未來的 Pubspec 欄位衝突。例如,您可以新增一個名為 my_pkg_bugs 的欄位,而不是新增 bugs

範例

#

一個簡單但完整的 Pubspec 如下所示

yaml
name: newtify
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '>=2.12.0 <3.0.0'
  
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
  
dev_dependencies:
  test: '>=1.15.0 <2.0.0'

詳細資料

#

本節提供有關每個 Pubspec 欄位的更多資訊。

名稱

#

每個套件都需要一個名稱。這是其他套件用來參照您的套件的方式,如果您要發布套件,這也是它對外顯示的方式。

名稱應全部使用小寫字母,並使用底線分隔字詞,just_like_this。僅使用基本拉丁字母和阿拉伯數字:[a-z0-9_]。此外,請確定名稱是有效的 Dart 識別碼,也就是說,它不會以數字開頭,也不會是 保留字

請嘗試選擇一個清楚、簡潔且尚未使用的名稱。建議您在 pub.dev 網站 上快速搜尋套件,以確定沒有其他套件正在使用您的名稱。

版本

#

每個套件都有版本。若要將您的套件寄存於 pub.dev 網站上,需要版本號碼,但對於僅限本地的套件,可以省略。如果您省略它,您的套件會隱含版本 0.0.0

版本控制對於在讓程式碼快速演進的同時重複使用程式碼是必要的。版本號碼是由點分隔的三個數字組成,例如 0.2.43。它也可以選擇性地加上組建 ( +1+2+hotfix.oopsie) 或預發行 (-dev.4-alpha.12-beta.7-rc.5) 字尾。

每次發佈套件時,您會在特定版本中發佈它。一旦完成,請將其視為密閉的:您無法再觸碰它。若要進行更多變更,您需要一個新版本。

當您選擇版本時,請遵循 語意化版本控制。

說明

#

這對於您自己的個人套件而言是可選的,但如果您打算發佈您的套件,您必須提供說明,說明應為英文。說明應相對簡短,介於 60 至 180 個字元之間,並告訴休閒讀者他們可能想知道的有關您的套件的資訊。

將說明視為您套件的銷售宣傳。使用者在 瀏覽套件時 會看到它。說明為純文字:沒有標記或 HTML。

首頁

#

這應為指向您套件網站的 URL。對於 已主控的套件,此 URL 會從套件頁面連結。雖然提供 homepage 是可選的,但請提供它或 repository(或兩者)。它有助於使用者了解您的套件來自何處。

儲存庫

#

可選的 repository 欄位應包含您套件的原始碼儲存庫的 URL,例如 https://github.com/<user>/<repository>。如果您將套件發佈到 pub.dev 網站,則您的套件頁面會顯示儲存庫 URL。雖然提供 repository 是可選的,但請提供它或 homepage(或兩者)。它有助於使用者了解您的套件來自何處。

問題追蹤器

#

可選的 issue_tracker 欄位應包含套件問題追蹤器的 URL,可以在其中檢視現有錯誤並提交新的錯誤。pub.dev 網站會嘗試使用此欄位的數值,顯示連結到每個套件的問題追蹤器。如果 issue_tracker 遺失,但 repository 存在且指向 GitHub,則 pub.dev 網站會使用預設問題追蹤器(https://github.com/<user>/<repository>/issues)。

文件

#

有些套件有一個網站主控文件,與主控首頁和 Pub 產生的 API 參考分開。如果您的套件有額外的文件,請新增一個 documentation: 欄位,其中包含該 URL;pub 會在您的套件頁面上顯示連結到此文件的連結。

相依性

#

相依性是 pubspec 的存在理由。在此部分中,您列出您的套件正常運作所需的每個套件。

相依性可分為兩種。一般相依性會列在 dependencies: 中,這些是使用套件的人員也需要的套件。套件本身開發階段才需要的相依性會列在 dev_dependencies 中。

在開發過程中,您可能需要暫時覆寫相依性。您可以使用 dependency_overrides 來這麼做。

如需詳細資訊,請參閱 套件相依性

可執行檔

#

套件可能會將一個或多個腳本公開為可直接從命令列執行的可執行檔。若要公開腳本,請在 executables 欄位中列出。項目會列為 key/value 成對

<name-of-executable>: <Dart-script-from-bin>

例如,下列 pubspec 項目列出兩個腳本

yaml
executables:
  slidy: main
  fvm:

使用 dart pub global activate 啟用套件後,輸入 slidy 會執行 bin/main.dart。輸入 fvm 會執行 bin/fvm.dart。如果您未指定值,系統會從 key 推斷。

如需詳細資訊,請參閱 pub global

平台

#

當您 發布套件 時,pub.dev 會自動偵測套件支援的平台。如果此平台支援清單不正確,請使用 platforms 明確宣告您的套件支援哪些平台。

例如,下列 platforms 項目會導致 pub.dev 將套件列為支援 Android、iOS、Linux、macOS、Web 和 Windows

yaml
# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

以下是宣告套件僅支援 Linux 和 macOS(例如不支援 Windows)的範例

yaml
# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

Publish_to

#

預設值使用 pub.dev 網站。指定 none 以防止發布套件。此設定可指定 自訂 pub 套件伺服器 來發布。

yaml
publish_to: none

資金

#

套件作者可以使用 funding 屬性指定一串網址,提供使用者如何協助資助套件開發的資訊。例如

yaml
funding:
 - https://www.buymeacoffee.com/example_user
 - https://www.patreon.com/some-account

如果發布至 pub.dev,連結會顯示在套件頁面上。這旨在協助使用者資助其相依項目的開發。

False_secrets

#

當您嘗試 發布套件 時,pub 會搜尋潛在的機密憑證、API 金鑰或加密金鑰外洩。如果 pub 在將發布的檔案中偵測到潛在的外洩,pub 會警告您並拒絕發布套件。

外洩偵測並不完美。為避免誤判,您可以使用 gitignore 模式 在 pubspec 中的 false_secrets 中建立允許清單,告訴 pub 不要在特定檔案中搜尋外洩。

例如,下列項目會導致 pub 不在檔案 lib/src/hardcoded_api_key.darttest/localhost_certificates/ 目錄中的所有 .pem 檔案中尋找外洩。

yaml
false_secrets:
 - /lib/src/hardcoded_api_key.dart
 - /test/localhost_certificates/*.pem

以斜線 (/) 開頭的 gitignore 模式可確保模式相對於套件的根目錄。

螢幕截圖

#

套件可以使用顯示在 pub.dev 頁面上的螢幕截圖來展示其小工具或其他視覺元素。若要指定套件要顯示的螢幕截圖,請使用 screenshots 欄位。

套件可以在 screenshots 欄位下最多列出 10 個螢幕截圖。請勿在此部分中包含標誌或其他品牌形象。每個螢幕截圖包含一個 description 和一個 pathdescription 說明螢幕截圖描述的內容,字數不得超過 160 個字元。例如

yaml
screenshots:
  - description: 'This screenshot shows the transformation of a number of bytes 
  to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
  representation.'
    path: path/to/image/in/package.png

Pub.dev 將螢幕截圖限制在以下規格中

  • 檔案大小:每個影像最大 4 MB。
  • 檔案類型:pngjpggifwebp
  • 靜態和動態影像皆允許。

保持螢幕截圖檔案大小。每次下載套件都會包含所有螢幕截圖檔案。

Pub.dev 會從第一個螢幕截圖產生套件的縮圖影像。如果此螢幕截圖使用動畫,pub.dev 會使用其第一個畫面。

主題

#

套件作者可以使用 topics 欄位來分類其套件。主題可用於協助在 pub.dev 上使用篩選器進行搜尋時的發現。Pub.dev 會在套件頁面以及搜尋結果中顯示主題。

此欄位包含一個名稱清單。例如

yaml
topics:
  - network
  - http

Pub.dev 要求主題遵循以下規格

  • 每個套件最多標記 5 個主題。
  • 請按照以下要求撰寫主題名稱
    • 使用 2 到 32 個字元。
    • 僅使用小寫字母數字字元或連字號 (a-z0-9-)。
    • 請勿使用兩個連續的連字號 (--)。
    • 名稱以小寫字母開頭 (a-z)。
    • 以字母數字字元結尾 (a-z0-9)。

選擇主題時,請考慮 現有主題 是否相關。使用現有主題標記有助於使用者發現您的套件。

Ignored_advisories

#

如果套件有受到安全性建議影響的相依項,pub 會在相依項解析期間針對建議發出警告。套件作者可以使用 ignored_advisories 欄位作為觸發建議的允許清單,這些建議與套件無關。

若要抑制有關建議的警告,請將建議識別碼新增至 ignored_advisories 清單。例如

yaml
name: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
 - GHSA-4rgh-jx4f-qfcq

如需更多資訊,請查看 安全性建議

SDK 約束

#

套件可以指出其支援的相依項版本,但套件有另一個隱含的相依項:Dart 平台本身。Dart 平台會隨著時間演進,而套件可能只適用於特定版本的平台。

套件可以使用SDK 約束來指定這些版本。此約束會放在 pubspec 中一個單獨的頂層 environment 欄位內,並使用與相依項相同的 版本約束 語法。

例如,下列約束表示此套件適用於任何版本 3.0.0 或更高的 Dart SDK

yaml
environment:
  sdk: ^3.0.0

Pub 會嘗試尋找 SDK 約束適用於您已安裝的 Dart SDK 版本的最新套件版本。

省略 SDK 約束會產生錯誤。當 pubspec 沒有 SDK 約束時,dart pub get 會傳回類似下列訊息的失敗訊息

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.0.0'
  
See http://dart.dev.org.tw/go/sdk-constraint

Flutter SDK 約束

#

Pub 支援在 environment: 欄位下指定 Flutter SDK 約束

yaml
environment:
  sdk: '>=1.19.0 <3.0.0'
  flutter: ^0.1.2

只有當 pub 在 flutter 可執行檔的背景下執行,且 Flutter SDK 的 version 檔案符合版本約束的下限時,才會滿足 Flutter SDK 約束。否則,不會選取該套件。

若要發佈具有 Flutter SDK 約束的套件,您必須指定 Dart SDK 約束,且最低版本至少為 1.19.0,以確保較舊版本的 pub 不會意外安裝需要 Flutter 的套件。