pubspec 檔案

目錄 keyboard_arrow_down keyboard_arrow_up

支援的欄位
範例
詳細資訊

more_horiz

每個 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 看起來像以下這樣

yamlname: 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: '^3.2.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 個字元—並告訴隨意閱讀的使用者他們可能想了解的有關您的套件的資訊。

將描述視為您套件的銷售宣傳。使用者在瀏覽套件時會看到它。描述是純文字：沒有 markdown 或 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 欄位下將其列出。條目以鍵/值對的形式列出

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

例如，以下 pubspec 條目列出了兩個腳本

yamlexecutables:
  slidy: main
  fvm:

一旦使用 dart pub global activate 啟動套件，輸入 slidy 就會執行 bin/main.dart。輸入 fvm 就會執行 bin/fvm.dart。如果您未指定值，則會從鍵推斷出來。

如需更多資訊，請參閱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:

預設使用 pub.dev 網站。指定 none 以防止套件被發佈。此設定可用於指定要發佈的自訂 pub 套件伺服器。

yaml

publish_to: none

套件作者可以使用 funding 屬性來指定 URL 清單，這些 URL 提供有關使用者如何幫助贊助套件開發的資訊。例如

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

如果發佈到 pub.dev，連結會顯示在套件頁面上。這旨在幫助使用者贊助其相依性的開發。

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

洩漏偵測並不完美。為了避免誤報，您可以告知 pub 不要搜尋某些檔案中的洩漏，方法是在 pubspec 中的 false_secrets 下使用 gitignore 模式建立允許清單。

例如，以下條目會導致 pub 不會在檔案 lib/src/hardcoded_api_key.dart 和 test/localhost_certificates/ 目錄中的所有 .pem 檔案中尋找洩漏

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

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

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

一個套件最多可以在 screenshots 欄位下列出 10 個螢幕截圖。請勿在此區段中包含標誌或其他品牌圖像。每個螢幕截圖都包含一個 description 和一個 path。description 解釋螢幕截圖所描繪的內容，字數不超過 160 個字元。例如

yamlscreenshots:
  - 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。
檔案類型：png、jpg、gif 或 webp。
靜態和動畫影像都允許。

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

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

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

該欄位由名稱清單組成。例如

yamltopics:
  - network
  - http

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

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

在選擇主題時，請考量現有主題是否相關。使用現有主題標記有助於使用者探索您的套件。

如果套件的相依性受到安全性公告的影響，則 pub 會在相依性解析期間警告有關該公告。套件作者可以使用 ignored_advisories 欄位作為與套件無關的觸發公告的允許清單。

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

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

如需更多資訊，請查看安全性公告。

套件可以指示它支援的相依性版本，但套件還有另一個隱式相依性：Dart 平台本身。Dart 平台會隨著時間推移而演進，而套件可能僅適用於平台的某些版本。

套件可以使用SDK 約束來指定這些版本。此約束位於 pubspec 中單獨的頂層 environment 欄位內，並使用與相依性相同的版本約束語法。

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

yamlenvironment:
  sdk: ^3.0.0

Pub 嘗試尋找與您安裝的 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.2.0'
  
See https://dart.dev.org.tw/go/sdk-constraint

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

yamlenvironment:
  sdk: ^3.2.0
  flutter: '>= 3.22.0'

僅當 pub 在 flutter 可執行檔的環境中執行時，且 Flutter SDK 的 version 檔案符合版本約束的下限時，Flutter SDK 約束才滿足。否則，將不會選擇該套件。

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

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

pubspec 檔案

支援的欄位

範例

詳細資訊

名稱

版本

描述

首頁

儲存庫

問題追蹤器

文件

相依性

可執行檔

平台

Publish_to

贊助

False_secrets

螢幕截圖

主題

Ignored_advisories

SDK 約束

Flutter SDK 約束