將您的程式庫發佈到 Maven Central – 教學

在本教學中，您將學習如何將 Kotlin Multiplatform 程式庫發佈到 Maven Central 存儲庫。

要發佈您的程式庫，您需要：

1. 設定憑據，包括 Maven Central 帳戶和用於簽名的 PGP 金鑰。
2. 在程式庫專案中配置發佈外掛程式。
3. 向發佈外掛程式提供您的憑據，以便它可以對您的構件進行簽名並上傳。
4. 執行發佈任務，可以在本機執行或使用持續整合。

本教學假設您：

• 正在建立一個開源程式庫。
• 將程式庫的程式碼存儲在 GitHub 存儲庫中。
• 使用 macOS 或 Linux。如果您是 Windows 使用者，請使用 GnuPG 或 Gpg4win 來產生金鑰對。
• 尚未在 Maven Central 註冊，或擁有適合發佈到 Central Portal 的現有帳戶（於 2024 年 3 月 12 日之後建立，或由其支援團隊遷移至 Central Portal）。
• 使用 GitHub Actions 進行持續整合。

如果您使用不同的設定，這裡的大部分步驟仍然適用，但可能需要考慮一些差異。

一個重要的限制是 Apple 目標必須在裝有 macOS 的電腦上建置。

範例程式庫

在本教學中，您將使用 fibonacci 程式庫作為範例。 您可以參考該存儲庫的程式碼，查看發佈設定是如何運作的。

如果您想重複使用該程式碼，您 必須將所有範例值替換為 您專案特定的值。

準備帳戶與憑據

要開始發佈到 Maven Central，請在 Maven Central 入口網站登入（或建立新帳戶）。

選擇並驗證命名空間

您需要一個經過驗證的命名空間，以便在 Maven Central 上唯一識別您程式庫的構件。

Maven 構件透過其座標進行識別，例如 com.example:fibonacci-library:1.0.0。這些座標由三個部分組成，並以冒號分隔：

• groupId：採用反向 DNS 形式，例如 com.example
• artifactId：程式庫本身的唯一名稱，例如 fibonacci-library
• version：版本字串，例如 1.0.0。版本可以是任何字串，但不能以 -SNAPSHOT 結尾

您註冊的命名空間允許您在 Maven Central 上設定 groupId 的格式。例如，如果您註冊了 com.example 命名空間，則可以發佈 groupId 設定為 com.example、com.example.libraryname、com.example.module.feature 等的構件。

登入 Maven Central 後，導航至 Namespaces 頁面。然後，點擊 Add Namespace 按鈕並註冊您的命名空間：

使用 GitHub 存儲庫使用網域名稱

如果您沒有網域名稱，使用您的 GitHub 帳戶建立命名空間是一個不錯的選擇：

1. 輸入 io.github.<your username> 作為您的命名空間，例如 io.github.kotlinhandson，然後點擊 Submit。
2. 複製新建立命名空間下方顯示的 Verification Key。
3. 在 GitHub 上，使用您使用的使用者名稱登入，並建立一個新的公用存儲庫，將驗證金鑰作為存儲庫名稱，例如 http://github.com/kotlin-hands-on/ex4mpl3c0d。
4. 返回 Maven Central 並點擊 Verify Namespace 按鈕。驗證成功後，您可以刪除所建立的存儲庫。

要將您擁有的網域名稱用作命名空間：

1. 使用反向 DNS 形式輸入您的網域作為命名空間。如果您的網域是 example.com，請輸入 com.example。

2. 複製顯示的 Verification Key。

3. 建立一個新的 TXT DNS 記錄，並將驗證金鑰作為其內容。

   請參閱 Maven Central 的 FAQ，以了解有關如何在各種網域註冊商執行此操作的更多資訊。

4. 返回 Maven Central 並點擊 Verify Namespace 按鈕。驗證成功後，您可以刪除所建立的 TXT 記錄。

產生金鑰對

在向 Maven Central 發佈內容之前，您需要使用 PGP 簽名對您的構件進行簽名，這允許使用者驗證構件的來源。

要開始簽名，您需要產生一個金鑰對：

• 私鑰 用於簽名您的構件，絕對不能與他人共享。
• 公鑰 可以與他人共享，以便他們驗證您構件的簽名。

使用 Kotlin Gradle 外掛程式使用 gpg 工具

Kotlin Gradle 外掛程式有一個 Gradle 任務，您可以用它來產生金鑰對。

1. 使用以下指令產生金鑰對。請按以下格式提供私鑰存儲庫的密碼和您的姓名：

   ./gradlew -Psigning.password=example-password generatePgpKeys --name "John Smith <[email protected]>"

   金鑰對存儲在 build/pgp 目錄中。

2. 將您的金鑰對從 build/pgp 目錄移至安全位置，以防止意外刪除或未經授權的存取。

可以為您管理簽名的 gpg 工具可在 GnuPG 網站上取得。您也可以使用 Homebrew 等套件管理器進行安裝：

brew install gpg

1. 使用以下指令開始產生金鑰對，並在提示時提供所需的詳細資訊：

   gpg --full-generate-key

2. 針對要建立的金鑰類型選擇建議的預設值。您可以保留選取項為空，然後按 Enter 鍵 以接受預設值。

   Please select what kind of key you want:
       (1) RSA and RSA
       (2) DSA and Elgamal
       (3) DSA (sign only)
       (4) RSA (sign only)
       (9) ECC (sign and encrypt) *default*
       (10) ECC (sign only)
       (14) Existing key from card
   Your selection? 9
   
   Please select which elliptic curve you want:
       (1) Curve 25519 *default*
       (4) NIST P-384
       (6) Brainpool P-256
   Your selection? 1

   在撰寫本文時，預設為使用 Curve 25519 的 ECC (sign and encrypt)。舊版本的 gpg 可能預設為金鑰大小為 3072 位元的 RSA。

3. 當提示指定金鑰的有效期限時，您可以選擇預設的「永久有效」選項。

   如果您選擇建立一個在設定時間後自動過期的金鑰，則需要在其過期時延長其有效期。

   Please specify how long the key should be valid.
       0 = key does not expire
       <n>  = key expires in n days
       <n>w = key expires in n weeks
       <n>m = key expires in n months
       <n>y = key expires in n years
   Key is valid for? (0) 0
   Key does not expire at all
   
   Is this correct? (y/N) y

4. 輸入您的姓名、電子郵件和選填註解，以便將金鑰與身分關聯（您可以將註解欄位留空）：

   GnuPG needs to construct a user ID to identify your key.
   
   Real name: Jane Doe
   Email address: [email protected]
   Comment:
   You selected this USER-ID:
       "Jane Doe <[email protected]>"

5. 輸入密碼短語以加密金鑰，並在提示時重複輸入。

   請妥善並私密地保存此密碼短語。稍後在簽名構件時，您將需要它來存取私鑰。

6. 使用以下指令查看您建立的金鑰：

   gpg --list-keys

   輸出看起來像這樣：

   pub   ed25519 2024-10-06 [SC]
         F175482952A225BFD4A07A713EE6B5F76620B385CE
   uid   [ultimate] Jane Doe <[email protected]>
         sub   cv25519 2024-10-06 [E]

   在接下來的步驟中，您將需要使用輸出中顯示的金鑰長英數識別符。

上傳公鑰

您需要將公鑰上傳至金鑰伺服器，以便 Maven Central 接受。有多個可用的金鑰伺服器，我們使用 keyserver.ubuntu.com 作為預設選擇。

使用 Kotlin Gradle 外掛程式使用 gpg 工具

Kotlin Gradle 外掛程式有一個 Gradle 任務，您可以用它來上傳公鑰。

執行以下指令上傳您的公鑰，並提供其路徑：

./gradlew uploadPublicPgpKey --keyring /path_to/build/pgp/public_KEY_ID.asc

您需要將公鑰上傳至金鑰伺服器，以便 Maven Central 接受。有多個可用的金鑰伺服器，我們使用 keyserver.ubuntu.com 作為預設選擇。

執行以下指令使用 gpg 上傳您的公鑰，並在參數中替換為您自己的金鑰 ID：

gpg --keyserver keyserver.ubuntu.com --send-keys F175482952A225BFC4A07A715EE6B5F76620B385CE

匯出您的私鑰

要讓您的 Gradle 專案存取您的私鑰，您需要將其匯出到檔案中。系統會提示您輸入建立金鑰時使用的密碼短語。

使用以下指令，傳入您自己的金鑰 ID 作為參數：

gpg --armor --export-secret-keys F175482952A225BFC4A07A715EE6B5F76620B385CE > key.gpg

此指令將建立一個包含您私鑰的 key.gpg 文字檔。

絕對不要與任何人共享您的私鑰檔案 – 只有您應該擁有存取權，因為私鑰可以使用您的憑據對檔案進行簽名。

配置專案

準備您的程式庫專案

如果您是從樣板專案開始開發程式庫，現在是將專案中任何預設名稱更改為與您自己的程式庫名稱匹配的好時機。這包括您的程式庫模組名稱，以及頂層 build.gradle.kts 檔案中的根專案名稱。

如果您的專案中有 Android 目標，您應該遵循準備 Android 程式庫發佈的步驟。此過程至少要求您為程式庫指定適當的命名空間，以便在編譯資源時產生唯一的 R 類別。請注意，此命名空間與先前建立的 Maven 命名空間不同。

// build.gradle.kts

android {
    namespace = "io.github.kotlinhandson.fibonacci"
}

設定發佈外掛程式

本教學使用 vanniktech/gradle-maven-publish-plugin 來協助發佈到 Maven Central。您可以在此處閱讀更多關於該外掛程式優點的資訊：here。請參閱外掛程式文件以了解有關其用法和可用配置選項的更多資訊。

要將外掛程式新增至專案，請在程式庫模組的 build.gradle.kts 檔案的 plugins {} 區塊中新增以下行：

// <module directory>/build.gradle.kts

plugins {
    id("com.vanniktech.maven.publish") version "0.34.0" 
}

有關外掛程式的最新可用版本，請查看其 Releases 頁面。

在同一個檔案中新增以下配置，並確保為您的程式庫自訂所有值：

// <module directory>/build.gradle.kts

mavenPublishing {
    publishToMavenCentral()
    
    signAllPublications()
    
    coordinates(group.toString(), "fibonacci", version.toString())
    
    pom { 
        name = "Fibonacci library"
        description = "A mathematics calculation library."
        inceptionYear = "2024"
        url = "https://github.com/kotlin-hands-on/fibonacci/"
        licenses {
            license {
                name = "The Apache License, Version 2.0"
                url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
                distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
            }
        }
        developers {
            developer {
                id = "kotlin-hands-on"
                name = "Kotlin Developer Advocate"
                url = "https://github.com/kotlin-hands-on/"
            }
        }
        scm {
            url = "https://github.com/kotlin-hands-on/fibonacci/"
            connection = "scm:git:git://github.com/kotlin-hands-on/fibonacci.git"
            developerConnection = "scm:git:ssh://[email protected]/kotlin-hands-on/fibonacci.git"
        }
    }
}

要配置此項，您也可以使用 Gradle 屬性。

這裡最重要的設定是：

• coordinates：指定程式庫的 groupId、artifactId 和 version。
• 授權：您的程式庫以此授權發佈。
• 開發者資訊：列出程式庫的作者。
• SCM (原始碼管理) 資訊：指定程式庫原始碼的代管位置。

執行本機檢查

在發佈到 Maven Central 之前，最好在本機檢查專案配置是否正確。

在本機檢查簽名

執行以下指令，驗證您的金鑰是否已針對簽名進行正確配置：

./gradlew checkSigningConfiguration

此 Gradle 任務會檢查您的公鑰是否已上傳到 keyserver.ubuntu.com 或 keys.openpgp.org 金鑰伺服器。

如果任務回報錯誤，請查看輸出以獲取有關如何修正的詳細資訊。

在本機檢查 pom.xml 檔案

要將您的程式庫發佈到 Maven Central，pom.xml 檔案必須符合 Maven Central 的需求。

對於您計劃發佈的每個程式庫，執行以下指令，並將 <PUBLICATION_NAME> 替換為發佈名稱：

./gradlew checkPomFileFor<PUBLICATION_NAME>Publication

使用 vanniktech/gradle-maven-publish-plugin 時，發佈通常命名為 Maven。在這種情況下，指令變為：

./gradlew checkPomFileForMavenPublication

如果任務回報錯誤，請查看輸出以獲取有關如何修正的詳細資訊。

使用持續整合發佈到 Maven Central

產生使用者權杖

您需要 Maven 存取權杖，Maven Central 才能授權您的發佈請求。開啟 Setup Token-Based Authentication 頁面，然後點擊 Generate User Token 按鈕。

輸出看起來像下面的範例，包含使用者名稱和密碼。如果您遺失了這些憑據，稍後需要重新產生，因為 Maven Central 不會存儲它們。

<server>
    <id>${server}</id>
    <username>l2nfaPmz</username>
    <password>gh9jT9XfnGtUngWTZwTu/8141keYdmQpipqLPRKeDLTh</password>
</server>

將 Secrets 新增至 GitHub

要在 GitHub Action 工作流程中使用發佈所需的金鑰和憑據並保持私密，您需要將這些值存儲為 Secrets（秘密）。

1. 在 GitHub 存儲庫的 Settings 頁面上，點擊 Security | Secrets and variables | Actions。

2. 點擊 New repository secret 按鈕並新增以下 Secrets：

   • MAVEN_CENTRAL_USERNAME 和 MAVEN_CENTRAL_PASSWORD：由 Central Portal 網站為 User Token 產生的值。
   • SIGNING_KEY_ID：簽名金鑰識別符的最後 8 個字元，例如 20B385CE（對應 F175482952A225BFC4A07A715EE6B5F76620B385CE）。
   • SIGNING_PASSWORD：您在產生 GPG 金鑰時提供的密碼短語。
   • GPG_KEY_CONTENTS：應包含您 key.gpg 檔案的全部內容。

   

您將在下一步的 CI 配置中使用這些 Secrets 的名稱。

將 GitHub Actions 工作流程新增至專案

您可以設定持續整合來自動建置並發佈您的程式庫。我們將以 GitHub Actions 為例。

首先，將以下工作流程新增至存儲庫中的 .github/workflows/publish.yml 檔案：

# .github/workflows/publish.yml

name: Publish
on:
  release:
    types: [released, prereleased]
jobs:
  publish:
    name: Release build and publish
    runs-on: macOS-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 21
      - name: Publish to MavenCentral
        run: ./gradlew publishToMavenCentral --no-configuration-cache
        env:
          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.SIGNING_KEY_ID }}
          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_KEY_CONTENTS }}

一旦您提交並推送此檔案，只要您在代管專案的 GitHub 存儲庫中建立發佈（包括預發佈），該工作流程就會自動執行。該工作流程會檢出程式碼的目前版本、設定 JDK，然後執行 publishToMavenCentral Gradle 任務。

使用 publishToMavenCentral 任務時，您仍需要在 Maven Central 網站上檢查並手動發佈您的部署。或者，您可以使用 publishAndReleaseToMavenCentral 任務來完全自動化發佈過程。

您也可以將工作流程配置為在將標籤推送到存儲庫時觸發。

上述腳本在 Gradle 指令中新增了 --no-configuration-cache，為發佈任務停用了 Gradle 配置快取，因為發佈外掛程式不支援該功能（請參閱此 待解決問題）。

此操作需要您的簽名詳細資訊和 Maven Central 憑據，即您建立的 repository secrets。

工作流程配置會自動將這些 Secrets 轉移到環境變數中，使它們可用於 Gradle 建置過程。

在 GitHub 上建立發佈

完成工作流程和 Secrets 設定後，您現在可以準備建立發佈，這將觸發程式庫的發佈。

1. 確保程式庫的 build.gradle.kts 檔案中指定的版本號碼是您想要發佈的版本。

2. 前往 GitHub 存儲庫的主頁。

3. 在右側側邊欄中，點擊 Releases。

4. 點擊 Draft a new release 按鈕（或者，如果您以前未曾為此存儲庫建立過發佈，則點擊 Create a new release 按鈕）。

5. 每個發佈都有一個標籤。在標籤下拉選單中建立一個新標籤，並設定發佈標題（標籤名稱和標題可以相同）。

   您可能希望這些名稱與您在 build.gradle.kts 檔案中指定的程式庫版本號碼相同。

   

6. 仔細檢查您要作為發佈目標的分支（特別是如果它不是預設分支），並為新版本新增適當的版本說明。

7. 使用描述下方的核取方塊將發佈標記為預發佈（對 Alpha、Beta 或 RC 等早期存取版本很有用）。

   您也可以將該發佈標記為最新版本（如果您以前已經為此存儲庫發佈過版本）。

8. 點擊 Publish release 按鈕以建立新發佈。

9. 點擊 GitHub 存儲庫頁面頂部的 Actions 標籤。在這裡，您將看到新發佈觸發了您的發佈工作流程。

   您可以點擊工作流程查看發佈任務的輸出。

10. 工作流程執行完成後，導航至 Maven Central 上的 Deployments 儀表板。您應該會在這裡看到一個新的部署。

    在 Maven Central 執行檢查時，此部署可能會在 pending（待處理）或 validating（驗證中）狀態停留一段時間。

11. 一旦您的部署處於 validated（已驗證）狀態，請檢查它是否包含您上傳的所有構件。如果一切看起來都正確，請點擊 Publish 按鈕來發佈這些構件。

    

    發佈後，構件需要一段時間（通常約為 15–30 分鐘，但也可能長達數小時）才能在 Maven Central 存儲庫中公開。它們可能需要更長時間才能被索引並在 Maven Central 網站上被搜尋到。

要在部署通過驗證後自動發佈構件，請將工作流程中的 publishToMavenCentral 任務替換為 publishAndReleaseToMavenCentral。

下一步

• 進一步了解設定多平台程式庫發佈和需求
• 將 shield.io 標記新增至您的 README
• 使用 Dokka 共享專案的 API 文件
• 新增 Renovate 以自動更新相依性
• 在 JetBrains 的搜尋平台上推廣您的程式庫
• 在 #feed Kotlin Slack 頻道與社群共享您的程式庫（要註冊，請造訪 https://kotl.in/slack）