目錄

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

觀看以下影片,了解套件的建置和發布概觀。

請記住:發佈是永久性的

#

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

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

對於已失去相關性或缺乏維護的已發布套件,將它們標記為已停用

準備套件以供發佈

#

發布套件時,請遵循 pubspec 格式套件佈局 結構中找到的慣例。為了簡化套件的使用,Dart 需要這些慣例。這些慣例包含連結指南中註明的部分例外。呼叫時,pub 會指出您可以進行哪些變更,讓您的套件在 Dart 生態系統中運作得更好。

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

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

  • 驗證您有合法權利重新分發您上傳為套件一部分的任何內容。

  • 將套件大小壓縮為小於 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 已驗證的發行者標誌

建立已驗證發佈者

#

如要建立 已驗證的發行者,請執行下列步驟

  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 檔案中列為要忽略的檔案和目錄

若要對 gitdart 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. 顯示它打算發佈的所有檔案。

  3. 將您的套件上傳至 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

發佈預發行版本

#

在開發套件時,請考慮將其發佈為預發行版本。當下列任何情況為真時,預發行版本會很有用

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

語意化版本管理 中所述,若要製作版本的預發行版本,請在版本中附加字尾。例如,若要製作版本 2.0.0 的預發行版本,您可以使用版本 2.0.0-dev.1。稍後,當您發佈版本 2.0.0 時,它會優先於所有 2.0.0-XXX 預發行版本。

由於 pub 在有穩定版本時會優先使用穩定版本,因此預發行套件的使用者可能需要變更其依賴項限制。例如,如果使用者想要測試版本 2.1 的預發行版本,則他們可能會指定 ^2.1.0-dev.1,而不是 ^2.0.0^2.1.0

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

發佈預覽版本

#

當下列所有情況為真時,預覽版本會很有用

  • 套件的下一穩定版本已完成。
  • 該套件版本依賴於 Dart SDK 中的 API 或功能,而該 API 或功能尚未在 Dart SDK 的穩定版本中發布。
  • 您知道套件依賴的 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. 按一下更新「建議的替代方案」

如果您改變心意,您可以隨時移除已停用的標記。