跳到主要內容
目錄

發布套件

目錄 keyboard_arrow_down keyboard_arrow_up
more_horiz

pub 套件管理器不僅僅是用於使用他人的套件。它也允許您與全世界分享您的套件。如果您有一個有用的專案，並且希望其他人能夠使用它，請使用 dart pub publish 命令。

觀看以下影片，以概略了解如何建置和發布套件。


如何在 Dart 中建置套件

請記住：發布是永久的

#

請記住，已發布的套件是永久存在的。一旦您發布套件，使用者就可以依賴它。一旦他們開始依賴它，移除套件將會破壞他們的專案。為了避免這種情況，pub.dev 政策禁止取消發布套件，除非在極少數情況下。

您可以隨時上傳套件的新版本，但舊版本仍可供尚無法升級的使用者使用。

對於已發布但已失去關聯性或缺乏維護的套件，請將其標記為已停止維護。

準備您的套件以進行發布

#

發布套件時，請遵循 pubspec 格式和 套件版面配置結構中的慣例。為了簡化您套件的使用，Dart 要求遵循這些慣例。這些慣例包含連結指南中註明的一些例外情況。當調用時，pub 會指出您可以進行哪些變更，以使您的套件在 Dart 生態系統中運作得更好。

除了這些慣例之外，您還必須遵循以下要求

  • 在您的套件中包含 LICENSE 檔案。我們建議使用 BSD 3 條款授權，Dart 和 Flutter 團隊通常使用此授權。但是，您可以使用任何適合您套件的授權。

  • 確認您擁有合法權利重新發布您作為套件一部分上傳的任何內容。

  • 在 gzip 壓縮後，保持套件大小小於 100 MB。如果太大，請考慮將其拆分為多個套件、使用 .pubignore 檔案移除不必要的內容，或減少包含的資源或範例數量。

  • 讓您的套件僅依賴預設 pub 套件伺服器上的託管相依性和 SDK 相依性 (sdk: flutter)。這些限制確保您套件的相依性在未來可以被找到和存取。

  • 擁有 Google 帳戶。Pub 使用 Google 帳戶來管理套件上傳權限。您的 Google 帳戶可以與 Gmail 地址或任何其他電子郵件地址相關聯。

填充您的 pub.dev 網頁

#

Pub 使用幾個檔案的內容在 pub.dev/packages/<your_package> 為您的套件建立頁面。以下檔案會影響您套件網頁的內容。

README.md
此檔案包含您套件網頁中呈現的主要內容。檔案的內容應使用 Markdown 標記。若要瞭解如何撰寫出色的 README，請參閱 撰寫套件頁面。
CHANGELOG.md
如果找到此檔案，它會在您套件的網頁上填充自己的分頁。開發人員可以直接從 pub.dev 閱讀您的變更。檔案的內容應使用 Markdown 標記。
pubspec.yaml
此檔案在您套件網頁的右側填充有關您套件的詳細資訊。檔案的內容應遵循 YAML 慣例。這些詳細資訊包括描述、首頁等等。

使用已驗證發布者的優點

#

您可以使用已驗證的發布者（推薦）或獨立的 Google 帳戶來發布套件。使用已驗證的發布者具有以下優點

  • 您套件的使用者知道發布者網域已驗證。
  • 您可以避免 pub.dev 顯示您的個人電子郵件地址。相反地，pub.dev 會顯示發布者網域和聯絡地址。
  • pub.dev 網站會在搜尋頁面和個別套件頁面上，在您的套件名稱旁邊顯示已驗證發布者徽章 pub.dev verified publisher logo。

建立已驗證的發布者

#

若要建立 已驗證的發布者，請依照下列步驟執行

  1. 前往 pub.dev。

  2. 使用 Google 帳戶登入 pub.dev。

  3. 從右上角的使用者選單中，選取 **建立發布者**。

  4. 輸入您想要與發布者關聯的網域名稱（例如，dart.dev）。

  5. 按一下 **建立發布者**。

  6. 在確認對話方塊中，選取 **確定**。

  7. 如果出現提示，請完成驗證流程。這會開啟 Google Search Console。

    • 新增 DNS 記錄時，可能需要幾個小時，Search Console 才會反映變更。
    • 驗證流程完成後，返回步驟 4。

發布您的套件

#

使用 dart pub publish 命令首次發布您的套件，或將其更新至新版本。

發布哪些檔案？

#

已發布的套件包含套件根目錄下的**所有檔案**，但有以下例外

  • 任何*隱藏*的檔案或目錄。這些檔案或目錄的名稱以點 (.) 開頭。
  • 在 .pubignore 或 .gitignore 檔案中列出要忽略的檔案和目錄

若要為 git 和 dart pub publish 使用不同的忽略規則，請建立 .pubignore 檔案以覆蓋指定目錄中的 .gitignore 檔案。如果目錄同時包含 .pubignore 檔案和 .gitignore 檔案，則 dart pub publish 會*忽略*該目錄的 .gitignore 檔案。.pubignore 檔案遵循與 .gitignore 檔案相同的格式。

為了避免發布不想要的檔案，請遵循以下做法

  • 刪除任何您不想包含的檔案，或將其新增到 .pubignore 或 .gitignore 檔案中。
  • 上傳套件時，請檢查 dart pub publish --dry-run 顯示將發布的檔案清單。如果該清單中出現任何不想要的檔案，請取消上傳。

測試發布您的套件

#

若要測試 dart pub publish 的運作方式，您可以執行試執行

$ dart pub publish --dry-run

使用此命令，dart pub 會執行以下工作

  1. 驗證您的套件是否遵循 pubspec 格式和 套件版面配置慣例。

  2. 顯示它打算發布的所有檔案。

以下範例顯示測試發布名為 transmogrify 的套件

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

發布到 pub.dev

#

當您的套件準備好發布時，請移除 --dry-run 引數

$ dart pub publish

使用此命令，dart pub 會執行以下工作

  1. 驗證您的套件是否遵循 pubspec 格式和 套件版面配置慣例。

  2. 驗證 git status 是否乾淨。如果 git 中追蹤的檔案有未提交的變更，則發出警告。

  3. 顯示它打算發布的所有檔案。

  4. 將您的套件上傳到 pub.dev。

在您的套件成功上傳到 pub.dev 後，任何 pub 使用者都可以下載它或在其專案中依賴它。

例如，如果您剛發布了 transmogrify 套件的 1.0.0 版本，則另一位 Dart 開發人員可以將其新增為他們 pubspec.yaml 中的相依性

yaml
dependencies:
  transmogrify: ^1.0.0

偵測支援的平台

#

pub.dev 網站會偵測套件支援哪些平台，並在套件頁面上顯示這些平台。pub.dev 的使用者可以依平台篩選搜尋。

若要變更產生的支援平台清單，請在 pubspec.yaml 檔案中指定支援的平台。

自動化發布

#

一旦您發布了套件的第一個版本，您就可以透過 GitHub Actions 或 Google Cloud 服務帳戶設定自動化發布。若要深入瞭解自動化發布，請參閱自動化發布套件到 pub.dev。

發布預發行版本

#

當您開發套件時，請考慮將其發布為預發行版本。在以下情況下，預發行版本可能很有用

  • 您正在積極開發套件的下一個主要版本。
  • 您想要為套件的下一個候選發行版本尋找 Beta 測試人員。
  • 套件依賴不穩定的 Dart 或 Flutter SDK 版本。

如 語意化版本控制 中所述，若要建立版本的預發行版本，請在版本後面附加字尾。例如，若要建立版本 2.0.0 的預發行版本，您可以使用版本 2.0.0-dev.1。稍後，當您發布版本 2.0.0 時，它會優先於所有 2.0.0-XXX 預發行版本。

由於 pub 在可用時偏好穩定版本，因此預發行套件的使用者可能需要變更其相依性約束。例如，如果使用者想要測試版本 2.1.0 的預發行版本，則他們可能會指定 ^2.1.0-dev.1，而不是 ^2.0.0 或 ^2.1.0。

當您將預發行版本發布到 pub.dev 時，套件頁面會顯示預發行版本和穩定版本的連結。預發行版本不會影響分析分數、顯示在搜尋結果中，或取代套件的 README.md 和文件。

發布預覽版本

#

當以下*所有*條件都成立時，預覽版本可能很有用

  • 套件的下一個穩定版本已完成。
  • 該套件版本依賴 Dart SDK 中尚未在穩定 Dart SDK 版本中發布的 API 或功能。
  • 您知道套件所依賴的 API 或功能是 API 穩定的，並且在達到穩定 SDK 之前不會變更。

例如，考慮 package:args 的新版本，其已完成版本 2.0.0。它依賴 Dart 3.0.0-417.1.beta 中的功能。但是，穩定版本的 Dart SDK 3.0.0 尚未發布。pubspec.yaml 檔案可能如下所示

pubspec.yaml
yaml
name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

當您將此套件發布到 pub.dev 時，它會被標記為預覽版本。以下螢幕擷取畫面說明了這一點。它將穩定版本列為 1.6.0，預覽版本列為 2.0.0。

Illustration of a preview version

當 Dart 發布穩定版本的 3.0.0 時，pub.dev 會更新套件清單，以將 2.0.0 顯示為套件的最新（穩定）版本。

如果本節開頭的所有條件都成立，請忽略來自 dart pub publish 的以下警告

"在 Dart SDK 預發行版本上具有 SDK 約束的套件本身應發布為預發行版本。如果此套件需要 Dart 版本 3.0.0-0，請考慮改為將套件發布為預發行版本。"

管理發布權限

#

尋找套件發布者

#

如果套件具有已驗證的發布者，則該套件的 pub.dev 頁面會顯示發布者網域。

對於在沒有發布者的情況下發布的套件，pub.dev 基於隱私原因不會透露發布者。**發布者**欄位會顯示「未驗證的上傳者」。

管理套件上傳者

#

無論是誰發布套件的第一個版本，都會成為第一個也是*唯一*授權上傳該套件其他版本的人。

若要允許或拒絕其他人上傳版本，請執行以下任一操作

  • 在套件的管理頁面上管理授權的上傳者：https://pub.dev/packages/<package>/admin。
  • 將套件轉移到已驗證的發布者；發布者的所有成員都已獲得授權可以上傳。

將套件轉移到已驗證的發布者

#

若要將套件轉移到已驗證的發布者，您必須是上傳者，並且是已驗證發布者的管理員。

若要將套件轉移到已驗證的發布者

  1. 使用列為套件上傳者的 Google 帳戶登入 pub.dev。

  2. 前往套件詳細資訊頁面（例如，https://pub.dev/packages/http）。

  3. 選取 **管理** 分頁。

  4. 輸入發布者的名稱，然後按一下 **轉移到發布者**。

管理您的套件

#

撤回套件版本

#

若要防止新的套件消費者在七天內採用您套件的已發布版本，您可以在發布後的七天內撤回該套件版本。撤回的版本可以在撤回後的七天內再次還原。

撤回不是刪除。撤回的套件版本會顯示在 pub.dev 上套件的版本清單的 **已撤回版本** 區段中。該套件版本的詳細檢視畫面會顯示 **已撤回** 徽章。

在撤回套件之前，請考慮改為發布新版本。撤回套件可能會對套件使用者產生負面影響。

如果您發布的新版本具有*遺失的相依性約束*或*寬鬆的相依性約束*，則撤回套件版本可能是唯一的解決方案。發布套件的較新版本不會阻止版本解析器選擇舊版本。該版本可能是 pub 可以選擇的唯一版本。撤回具有不正確相依性約束的套件版本會強制使用者升級其他相依性或產生相依性衝突。

但是，如果您的套件包含小錯誤，您可能不需要撤回版本。發布已修正錯誤的新版本，並在 CHANGELOG.md 中描述已修正的錯誤。這有助於使用者瞭解發生了什麼事。發布新版本對套件使用者的干擾較小。

如何使用已撤回的套件版本

#

如果套件依賴稍後被撤回的套件版本，只要該版本在相依套件的 pubspec.lock 檔案中，它仍然可以使用該版本。若要依賴已撤回的特定版本，相依套件必須在 pubspec.yaml 檔案的 dependency_overrides 區段中釘選該版本。

如何從已撤回的套件版本遷移

#

當套件依賴已撤回的套件版本時，您可以根據其他可用版本選擇如何從此版本遷移。

升級到較新版本

#

在大多數情況下，已發布較新版本以取代撤回的版本。在這種情況下，請執行 dart pub upgrade <package>。

降級到最新的未撤回版本

#

如果沒有較新版本可用，請考慮降級到最新的未撤回版本。您可以使用以下兩種方式之一執行此操作。

  1. 使用 pub 工具命令

    1. 執行 dart pub downgrade <package> 以取得與 pubspec.yaml 檔案中約束條件相符的指定套件的最低版本。

    2. 執行 dart pub upgrade <package> 以取得可用的最新相容且未撤回的版本。

  2. 在您偏好的 IDE 中編輯 pubspec.lock 檔案

    1. 刪除具有撤回版本的套件的整個套件項目。

    2. 執行 dart pub get 以取得可用的最新相容且未撤回的版本。

雖然您可以刪除 pubspec.lock 檔案並執行 dart pub get，但不建議這樣做。這可能會導致其他相依性的版本變更。

升級或降級到指定版本約束之外的版本

#

如果沒有可用的替代版本滿足目前的版本約束，請編輯 pubspec.yaml 檔案中的版本約束，然後執行 dart pub upgrade。

如何撤回或還原套件版本

#

若要撤回或還原套件版本，請先使用 Google 帳戶登入 pub.dev，該帳戶必須是套件的上傳者或已驗證發布者管理員。然後前往套件的「管理」分頁，您可以在其中撤回或還原最近的套件版本。

停止維護套件

#

雖然套件仍保持發布狀態，但您可以向開發人員示意套件不再進行積極維護。這需要您將套件標記為**已停止維護**。

一旦您停止維護套件，該套件將會

  • 保持在 pub.dev 上發布。
  • 保持在 pub.dev 上可檢視。
  • 顯示清晰的 **已停止維護** 徽章。
  • 不會出現在 pub.dev 搜尋結果中。

若要將套件標記為已停止維護

  1. 使用具有套件上傳者或已驗證發布者權限的 Google 帳戶登入 pub.dev。

  2. 導覽至套件的 **管理** 分頁。

  3. 若要停止維護套件，請選取 **標記為「已停止維護」**。

您也可以推薦替代套件。

  1. 在 **建議的替代方案** 下方的欄位中，輸入另一個套件的名稱。

  2. 按一下 **更新「建議的替代方案」**。

如果您改變主意，您可以隨時移除已停止維護標記。

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