在 Gradle Plugin Portal 發佈外掛

發布外掛程式是讓其他人可以使用它的主要方式。雖然您可以發布到私人儲存庫以限制存取，但發布到 Gradle 外掛程式入口網站會讓全世界任何人都可以使用您的外掛程式。

本指南說明如何使用 com.gradle.plugin-publish 外掛，使用方便的 DSL 將外掛發佈到 Gradle 外掛入口網站。此方法簡化了設定步驟，並提供驗證檢查，以確保您的外掛符合 Gradle 外掛入口網站的標準。

先決條件

您需要一個現有的 Gradle 外掛專案才能進行本教學課程。如果您沒有，請使用問候語外掛範例。

嘗試發佈此外掛會安全地失敗並出現權限錯誤，因此不必擔心使用微不足道的外掛範例讓 Gradle 外掛入口網站變得雜亂。

帳戶設定

在發佈您的外掛之前，您必須在 Gradle 外掛入口網站上建立帳戶。請遵循註冊頁面上的說明，建立帳戶並從您的個人資料頁面的「API 金鑰」標籤取得 API 金鑰。

將您的 API 金鑰儲存在您的 Gradle 設定中 (gradle.publish.key 和 gradle.publish.secret)，或使用 Seauc Credentials 外掛或 Gradle Credentials 外掛等外掛進行安全管理。

一般做法是將文字複製並貼到您的 $HOME/.gradle/gradle.properties 檔案中，但您也可以將其放在任何其他有效的位置。外掛僅需要在執行適當的外掛入口網站任務時，gradle.publish.key 和 gradle.publish.secret 可用為專案屬性即可。

如果您擔心將您的憑證放在 gradle.properties 中，請查看 Seauc Credentials 外掛或 Gradle Credentials 外掛。

新增外掛發佈外掛

若要發佈您的外掛，請將 com.gradle.plugin-publish 外掛新增到您的專案的 build.gradle 或 build.gradle.kts 檔案

build.gradle.kts

plugins {
    id("com.gradle.plugin-publish") version "1.2.1"
}

build.gradle

plugins {
    id 'com.gradle.plugin-publish' version '1.2.1'
}

可以在 Gradle 外掛入口網站上找到最新版本的「外掛發佈外掛」。

從版本 1.0.0 開始，外掛發佈外掛會自動套用 Java Gradle 外掛開發外掛 (協助開發 Gradle 外掛) 和 Maven 發佈外掛 (產生外掛發佈的元資料)。如果使用較舊版本的外掛發佈外掛，則必須明確套用這些輔助外掛。

設定外掛發佈外掛

在您的 build.gradle 或 build.gradle.kts 檔案中設定 com.gradle.plugin-publish 外掛。

build.gradle.kts

group = "io.github.johndoe" (1)
version = "1.0" (2)

gradlePlugin { (3)
    website = "<substitute your project website>" (4)
    vcsUrl = "<uri to project source repository>" (5)

    // ... (6)
}

build.gradle

group = 'io.github.johndoe' (1)
version = '1.0'     (2)

gradlePlugin { (3)
    website = '<substitute your project website>' (4)
    vcsUrl = '<uri to project source repository>' (5)

    // ... (6)
}

1	確定您的專案具有用於識別您在 Gradle Plugin Portal 儲存庫中發佈的成品 (jar 和元資料) 的 `group` 設定，且該設定描述了外掛作者或外掛所屬的組織。
2	設定專案版本，該版本也會用作外掛的版本。
3	使用 Java Gradle Plugin Development Plugin 提供的 `gradlePlugin` 區塊，為外掛發佈設定更多選項。
4	設定外掛專案的網站。
5	提供原始程式碼儲存庫 URI，以便其他人可以在需要時找到它並參與貢獻。
6	設定您要發佈的每個外掛的特定屬性；請參閱下一部分。

使用 gradlePlugin{} 區塊，定義所有外掛的共用屬性，例如群組、版本、網站和原始程式碼儲存庫

build.gradle.kts

gradlePlugin { (1)
    // ... (2)

    plugins { (3)
        create("greetingsPlugin") { (4)
            id = "<your plugin identifier>" (5)
            displayName = "<short displayable name for plugin>" (6)
            description = "<human-readable description of what your plugin is about>" (7)
            tags = listOf("tags", "for", "your", "plugins") (8)
            implementationClass = "<your plugin class>"
        }
    }
}

build.gradle

gradlePlugin { (1)
    // ... (2)

    plugins { (3)
        greetingsPlugin { (4)
            id = '<your plugin identifier>' (5)
            displayName = '<short displayable name for plugin>' (6)
            description = '<human-readable description of what your plugin is about>' (7)
            tags.set(['tags', 'for', 'your', 'plugins']) (8)
            implementationClass = '<your plugin class>'
        }
    }
}

1	外掛特定設定也會放入 `gradlePlugin` 區塊。
2	這是我們先前新增全域屬性的位置。
3	您發佈的每個外掛都會在 `plugins` 內有自己的區塊。
4	每個您發佈的外掛，其外掛區塊的名稱都必須是唯一的；這是一個僅供您的建置在本地使用的屬性，不會是發佈的一部分。
5	設定外掛的唯一 `id`，因為它會在發佈中被識別。
6	設定外掛名稱，以人類可讀的形式呈現。
7	設定要顯示在入口網站上的說明。它會提供有用的資訊給想要使用您的外掛的人。
8	指定您的外掛涵蓋的類別。這會讓需要其功能的人更有可能發現外掛。

例如，考慮已經發佈到 Gradle Plugin Portal 的 GradleTest 外掛設定。

build.gradle.kts

gradlePlugin {
    website = "https://github.com/ysb33r/gradleTest"
    vcsUrl = "https://github.com/ysb33r/gradleTest.git"
    plugins {
        create("gradletestPlugin") {
            id = "org.ysb33r.gradletest"
            displayName = "Plugin for compatibility testing of Gradle plugins"
            description = "A plugin that helps you test your plugin against a variety of Gradle versions"
            tags = listOf("testing", "integrationTesting", "compatibility")
            implementationClass = "org.ysb33r.gradle.gradletest.GradleTestPlugin"
        }
    }
}

build.gradle

gradlePlugin {
    website = 'https://github.com/ysb33r/gradleTest'
    vcsUrl = 'https://github.com/ysb33r/gradleTest.git'
    plugins {
        gradletestPlugin {
            id = 'org.ysb33r.gradletest'
            displayName = 'Plugin for compatibility testing of Gradle plugins'
            description = 'A plugin that helps you test your plugin against a variety of Gradle versions'
            tags.addAll('testing', 'integrationTesting', 'compatibility')
            implementationClass = 'org.ysb33r.gradle.gradletest.GradleTestPlugin'
        }
    }
}

如果您瀏覽 GradleTest 外掛在 Gradle Plugin Portal 上的關聯頁面，您會看到指定的元資料是如何顯示的。

publishing {
    repositories {
        maven {
            name = "localPluginRepository"
            url = uri("../local-plugin-repository")
        }
    }
}

build.gradle

publishing {
    repositories {
        maven {
            name = 'localPluginRepository'
            url = '../local-plugin-repository'
        }
    }
}

若要在其他組建中使用儲存庫，請將其新增到 settings.gradle(.kts) 檔案中 pluginManagement {} 區塊的儲存庫。

發布到外掛入口網站

使用 publishPlugin 任務發布外掛

$ ./gradlew publishPlugins

您可以在發布之前使用 --validate-only 旗標驗證外掛

$ ./gradlew publishPlugins --validate-only

如果您尚未為 Gradle 外掛入口網站設定 gradle.properties，您可以在命令列中指定它們

$ ./gradlew publishPlugins -Pgradle.publish.key=<key> -Pgradle.publish.secret=<secret>

如果您嘗試使用本節中使用的 ID 發布範例問候外掛，您會遇到權限失敗。這是預期的，並確保入口網站不會被多個實驗性和重複的問候類型外掛所淹沒。

經核准後，您的外掛將在 Gradle 外掛入口網站上提供，供其他人發現和使用。

使用已發布的外掛

成功發布外掛後，它不會立即出現在入口網站上。它還需要通過核准程序，對於外掛的初始版本來說，這是一個手動且相對緩慢的程序，但對於後續版本來說，則完全自動化。如需進一步的詳細資訊，請在此處參閱。

一旦您的外掛程式獲得核准，您可以在網址 https://plugins.gradle.org/plugin/<your-plugin-id> 找到其使用說明。例如，Greeting 外掛程式範例已在入口網站上，網址為 https://plugins.gradle.org/plugin/org.example.greeting。

未透過 Gradle 外掛程式入口網站發布的外掛程式

如果您未透過 Java Gradle 外掛程式開發外掛程式發布外掛程式，則該發布將缺少外掛程式標記人工製品，而外掛程式 DSL 需要此人工製品才能找到外掛程式。在此情況下，建議在專案設定檔的 pluginManagement {} 區塊中新增 resolutionStrategy 區段來解析另一個專案中的外掛程式，如下所示。

settings.gradle.kts

resolutionStrategy {
    eachPlugin {
        if (requested.id.namespace == "org.example") {
            useModule("org.example:custom-plugin:${requested.version}")
        }
    }
}

settings.gradle

resolutionStrategy {
    eachPlugin {
        if (requested.id.namespace == 'org.example') {
            useModule("org.example:custom-plugin:${requested.version}")
        }
    }
}

此頁面有幫助嗎？

在 Gradle Plugin Portal 發佈外掛

先決條件

帳戶設定

新增外掛發佈外掛

設定外掛發佈外掛

原始程式碼和 Javadoc

簽署成品

影子相依性

發布外掛

本地發布

發布到外掛入口網站

使用已發布的外掛

未透過 Gradle 外掛程式入口網站發布的外掛程式