釋出軟體包

pub 軟體包管理器 不僅用於使用其他人的軟體包，它也允許你與全世界分享你的軟體包。如果你有一個實用的專案並且希望其他人能夠使用它，可以使用 dart pub publish 命令。

觀看以下影片，瞭解構建和釋出軟體包的概覽。

請記住，釋出的軟體包是永久性的。一旦你釋出了軟體包，使用者就可以依賴它。一旦他們開始依賴它，移除該軟體包會破壞他們的專案。為了避免這種情況，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 使用一些檔案的內容來為你的軟體包在 pub.dev/packages/<你的軟體包名稱> 上建立頁面。以下檔案會影響你的軟體包網頁的內容。

README.md

此檔案包含你軟體包網頁上的主要內容。檔案內容應使用 Markdown 進行標記。要了解如何編寫出色的 README，請參閱編寫軟體包頁面。

CHANGELOG.md

如果存在，此檔案會在你的軟體包網頁上填充一個單獨的標籤頁。開發者可以直接從 pub.dev 讀取你的更改。檔案內容應使用 Markdown 進行標記。

pubspec.yaml

此檔案在你軟體包網頁的右側填充有關軟體包的詳細資訊。檔案內容應遵循 YAML 約定。這些詳細資訊包括描述、主頁等。

你可以使用認證釋出者（推薦）或獨立的 Google 賬號釋出軟體包。使用認證釋出者具有以下優勢

• 你的軟體包的使用者知道釋出者域名已透過認證。
• 你可以避免在 pub.dev 上顯示你的個人電子郵件地址。相反，pub.dev 會顯示釋出者域名和聯絡地址。
• pub.dev 網站會在搜尋頁面和單個軟體包頁面上，在你的軟體包名稱旁邊顯示一個認證釋出者徽章 。

要建立認證釋出者，請按照以下步驟操作

1. 前往 pub.dev。

2. 使用 Google 賬號登入 pub.dev。

3. 從右上角的使用者選單中選擇 Create Publisher。

4. 輸入你想與釋出者關聯的域名（例如，dart.dev）。

5. 點選 Create Publisher。

6. 在確認對話方塊中，選擇 OK。

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 將如何工作，你可以執行一次模擬執行（dry run）

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.

準備好釋出軟體包時，移除 --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 中將其新增為依賴項

dependencies:
  transmogrify: ^1.0.0

pub.dev 網站會檢測軟體包支援哪些平臺，並在軟體包頁面上顯示這些平臺。pub.dev 的使用者可以按平臺過濾搜尋結果。

要更改生成的支援平臺列表，請在 pubspec.yaml 檔案中指定支援的平臺。

釋出第一個版本的軟體包後，你可以透過 GitHub Actions 或 Google Cloud 服務賬號配置自動化釋出。要了解更多關於自動化釋出的資訊，請查閱將軟體包自動化釋出到 pub.dev。

在開發軟體包時，考慮將其釋出為預釋出版本（prerelease）。預釋出版本在以下情況下很有用：

• 你正在積極開發軟體包的下一個主版本。
• 你希望為軟體包的下一個釋出候選版本尋找 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 檔案可能如下所示

name: args
version: 2.0.0

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

當你將此軟體包釋出到 pub.dev 時，它會被標記為預覽版本。以下截圖對此進行了說明。它將穩定版本列為 1.6.0，將預覽版本列為 2.0.0。

當 Dart 釋出 3.0.0 的穩定版本時，pub.dev 會更新軟體包列表，將 2.0.0 顯示為軟體包的最新（穩定）版本。

如果本節開頭的所有條件都滿足，請忽略 dart pub publish 發出的以下警告

“對 Dart SDK 的預釋出版本有 SDK 約束的軟體包本身應作為預釋出版本釋出。如果此軟體包需要 Dart 3.0.0-0 版本，請考慮將軟體包作為預釋出版本釋出。”

如果軟體包有認證釋出者，該軟體包的 pub.dev 頁面會顯示釋出者域名。

對於沒有釋出者釋出的軟體包，pub.dev 基於隱私原因不公開發布者資訊。Publisher（釋出者）欄位顯示“未認證上傳者”。

首次釋出軟體包的人成為第一個也是唯一獲授權上傳該軟體包新版本的人。

要允許或不允許其他人上傳版本，可以

• 在軟體包的管理頁面上管理授權的上傳者：https://pub.dev/packages/<軟體包名稱>/admin。
• 將軟體包轉移給認證釋出者；釋出者的所有成員都有上傳許可權。

要將軟體包轉移給認證釋出者，你必須是該軟體包的上傳者，並且是認證釋出者的管理員。

將軟體包轉移給認證釋出者

1. 使用 Google 賬號登入 pub.dev，該賬號必須是軟體包的上傳者之一。

2. 前往軟體包詳情頁面（例如，https://pub.dev/packages/http）。

3. 選擇 Admin（管理）標籤頁。

4. 輸入釋出者的名稱，然後點選 Transfer to Publisher（轉移給釋出者）。

為了防止新的軟體包使用者在七天視窗期內採用你已釋出的軟體包版本，你可以在釋出後的七天內撤回該軟體包版本。撤回的版本可以在撤回後的七天內再次恢復。

撤回並非刪除。撤回的軟體包版本會顯示在 pub.dev 上該軟體包版本列表的 Retracted versions（已撤回版本）部分。該軟體包版本的詳細檢視會顯示一個 RETRACTED（已撤回）徽章。

在撤回軟體包之前，考慮釋出一個新版本。撤回軟體包可能會對軟體包使用者產生負面影響。

如果你釋出的新版本存在缺失的依賴項約束或寬鬆的依賴項約束，那麼撤回軟體包版本可能是唯一的解決方案。釋出軟體包的新版本並不會阻止版本解析器選擇舊版本。該版本可能是 pub 可以選擇的唯一版本。撤回帶有錯誤依賴項約束的軟體包版本會強迫使用者升級其他依賴項或導致依賴項衝突。

但是，如果你的軟體包包含一個小錯誤，你可能不需要撤回該版本。釋出一個修復了錯誤的新版本，並在 CHANGELOG.md 中描述修復的錯誤。這有助於使用者理解發生了什麼。釋出新版本對軟體包使用者的干擾較小。

如果一個軟體包依賴於後來被撤回的軟體包版本，只要該版本存在於依賴軟體包的 pubspec.lock 檔案中，仍然可以使用該版本。要依賴一個已撤回的特定版本，依賴軟體包必須在 pubspec.yaml 檔案的 dependency_overrides 部分中指定該版本。

當一個軟體包依賴於已撤回的軟體包版本時，根據其他可用版本，你有幾種遷移方式可供選擇。

在大多數情況下，已釋出新版本來替換已撤回的版本。在這種情況下，執行 dart pub upgrade <軟體包名稱>。

如果沒有可用的新版本，考慮降級到最新的非撤回版本。你可以透過以下兩種方式之一來實現。

1. 使用 pub 工具命令

   1. 執行 dart pub downgrade <軟體包名稱> 以獲取指定軟體包的符合 pubspec.yaml 檔案中約束的最低版本。

   2. 執行 dart pub upgrade <軟體包名稱> 以獲取最新的相容且未撤回的可用版本。

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

   1. 刪除帶有已撤回版本的軟體包的整個條目。

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

儘管你可以刪除 pubspec.lock 檔案並執行 dart pub get，但這不推薦。這可能會導致其他依賴項的版本發生變化。

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

要撤回或恢復軟體包版本，首先使用一個 Google 賬號登入 pub.dev，該賬號是該軟體包的上傳者或認證釋出者管理員。然後前往軟體包的 Admin（管理）標籤頁，在那裡可以撤回或恢復最近的軟體包版本。

儘管軟體包仍然釋出，你可以向開發者表明軟體包沒有進行積極維護。這需要你將軟體包標記為已停止維護。

一旦你停止維護一個軟體包，該軟體包將

• 仍在 pub.dev 上釋出。
• 仍在 pub.dev 上可檢視。
• 顯示一個清晰的 DISCONTINUED（已停止維護）徽章。
• 不會出現在 pub.dev 的搜尋結果中。

將軟體包標記為已停止維護

1. 使用對該軟體包具有上傳者或認證釋出者許可權的 Google 賬號登入 pub.dev。

2. 導航到軟體包的 Admin（管理）標籤頁。

3. 要停止維護軟體包，選擇 Mark "discontinued"（標記為“已停止維護”）。

你還可以推薦一個替代軟體包。

1. 在 Suggested replacement（建議替代）欄位下，輸入另一個軟體包的名稱。

2. 點選 Update "Suggested Replacement"（更新“建議替代”）。

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