在 Gradle 插件门户发布插件

发布插件是使其可供他人使用的主要方式。虽然你可以发布到私有存储库以限制访问，但发布到 Gradle 插件门户会让全世界任何人都可以使用你的插件。

本指南将向你展示如何使用 com.gradle.plugin-publish 插件使用便捷的 DSL 将插件发布到 Gradle 插件门户。此方法简化了配置步骤，并提供了验证检查，以确保你的插件符合 Gradle 插件门户的标准。

先决条件

本教程需要一个现有的 Gradle 插件项目。如果没有，请使用 Greeting 插件示例。

尝试发布此插件会因权限错误而安全失败，因此不必担心用一个简单的示例插件弄乱 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	确保您的项目已设置 `group`，该 `group` 用于标识您在 Gradle 插件门户的存储库中为插件发布的工件（jar 和元数据），并且该 `group` 描述了插件作者或插件所属的组织。
2	设置项目的版本，该版本也将用作插件的版本。
3	使用 Java Gradle 插件开发插件提供的 `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	指定插件涵盖的类别。这样，需要插件功能的人更有可能发现该插件。

例如，考虑 GradleTest 插件的配置，该插件已发布到 Gradle 插件门户。

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 插件门户上的关联页面，您将看到指定的元数据是如何显示的。

源和 Javadoc

插件发布插件会自动生成并发布 Javadoc 和源 JAR 以供您的插件发布使用。

签名工件

从插件发布插件的 1.0.0 版本开始，已自动执行已发布插件工件的签名。要启用它，您只需在构建中应用 signing 插件。

影子依赖项

从插件发布插件的 1.0.0 版本开始，已自动执行插件依赖项的影子化（即，将其发布为 fat jar）。要启用它，您只需在构建中应用 com.github.johnrengelman.shadow 插件。

发布插件

如果您在组织内部发布插件以供使用，则可以像发布任何其他代码工件一样发布它。请参阅 Ivy 和 Maven 章节，了解如何发布工件。

如果您有兴趣发布插件以供更广泛的 Gradle 社区使用，则可以将其发布到 Gradle 插件门户。该网站提供了搜索和收集 Gradle 社区提供的插件信息的能力。请参阅相应的部分，了解如何在该网站上提供您的插件。

在本地发布

要检查已发布插件的工件的外观或仅在本地或公司内部使用它，您可以将其发布到任何 Maven 存储库，包括本地文件夹。您只需配置用于发布的存储库。然后，您可以运行 publish 任务，将插件发布到您定义的所有存储库（但不是 Gradle 插件门户）。

build.gradle.kts

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 发布示例 Greeting 插件，您将遇到权限失败。这是预期的，并确保门户不会被多个实验性和重复的 greeting 类型插件所覆盖。

经过批准后，您的插件将在 Gradle 插件门户上供其他人发现和使用。

使用已发布的插件

成功发布插件后，它不会立即出现在门户上。它还需要通过审批流程，对于插件的初始版本来说，该流程是手动且相对较慢的，但对于后续版本来说是完全自动的。有关更多详细信息，请参阅此处。

一旦您的插件获得批准，您可以在 https://plugins.gradle.org.cn/plugin/<your-plugin-id> 形式的 URL 中找到有关其使用说明。例如，Greeting 插件示例已在 https://plugins.gradle.org.cn/plugin/org.example.greeting 上的 portal 中。

未通过 Gradle 插件门户发布的插件

如果您的插件未使用 Java Gradle 插件开发插件发布，则该出版物将缺少插件标记工件，这是 plugins 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}")
        }
    }
}

此页面有帮助吗？