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，使用者可以在其中檢視現有 bug 和提交新 bug。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 列表，其中包含使用者如何資助包開發的資訊。例如

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

如果釋出到 pub.dev，這些連結會顯示在包頁面上。這旨在幫助使用者資助其依賴項的開發。

當您嘗試釋出包時，pub 會搜尋是否存在秘密憑據、API 金鑰或加密金鑰的潛在洩露。如果 pub 檢測到某個將要釋出的檔案中存在潛在洩露，則 pub 會警告您並拒絕釋出該包。

洩露檢測並非完美無缺。為了避免誤報，您可以透過在 pubspec 的 false_secrets 下使用 gitignore 模式建立允許列表，來告訴 pub 不要在某些檔案中搜索洩露。

例如，以下條目導致 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.lang.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 約束的包，您必須指定一個最低版本為 1.19.0 或更高的 Dart SDK 約束，以確保舊版本的 pub 不會意外安裝需要 Flutter 的包。

此頁面內容對您有幫助嗎？

感謝您的反饋！

提供詳情

感謝您的反饋！請告訴我們如何改進。

提供詳情

除非另有說明，本網站的文件反映 Dart 3.8.1 版本。頁面上次更新於 2025-05-29。檢視原始檔或報告問題。

pubspec 檔案

支援的欄位

示例

詳情

名稱

版本

描述

主頁

倉庫

問題追蹤器

文件

依賴項

可執行檔案

平臺

Publish_to

資助

False_secrets

螢幕截圖

主題

Ignored_advisories

SDK 約束

Flutter SDK 約束