发布插件到 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 文件中，但您也可以将其放置在任何其他有效位置。所有插件的要求是，当执行适当的 Plugin Portal 任务时，gradle.publish.key 和 gradle.publish.secret 可作为项目属性使用。

如果您担心将凭据放置在 gradle.properties 中，请查看 Seauc Credentials 插件或 Gradle Credentials 插件。

或者，您可以通过 GRADLE_PUBLISH_KEY 和 GRADLE_PUBLISH_SECRET 环境变量提供 API 密钥。这种方法可能对 CI/CD 管道很有用。

添加 Plugin Publishing 插件

要发布您的插件，请将 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'
}

Plugin Publishing 插件的最新版本可以在 Gradle 插件门户上找到。

自 1.0.0 版本起，Plugin Publish 插件自动应用 Java Gradle Plugin Development 插件 (协助开发 Gradle 插件) 和 Maven Publish 插件 (生成插件发布元数据)。如果使用旧版本的 Plugin Publish 插件，则必须显式应用这些辅助插件。

配置 Plugin Publishing 插件

在您的 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`，该组用于标识您为 Gradle 插件门户的仓库中的插件发布的工件（jar 和元数据），并且描述了插件作者或插件所属的组织。
2	设置您的项目版本，该版本也将用作您的插件的版本。
3	使用 Java Gradle Plugin Development 插件提供的 `gradlePlugin` 代码块，为您的插件发布配置更多选项。
4	设置您的插件项目网站。
5	提供源代码仓库 URI，以便其他人可以找到它（如果他们想贡献代码）。
6	为您要发布的每个插件设置特定的属性；请参阅下一节。

使用 gradlePlugin{} 代码块定义所有插件的通用属性，例如 group、version、website 和 source repository

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 插件门户的 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'
        }
    }
}

如果您浏览 Gradle 插件门户上与 GradleTest 插件关联的页面，您将看到指定的元数据是如何显示的。

Sources & Javadoc

Plugin Publish 插件自动生成并发布您的插件发布的 Javadoc 和 sources JAR。

签名工件

从 Plugin Publish 插件 1.0.0 版本开始，已发布插件工件的签名已实现自动化。要启用它，只需在您的构建中应用 signing 插件即可。

Shadow 依赖

从 Plugin Publish 插件 1.0.0 版本开始，插件依赖的 Shadow 处理（即，将其作为 fat jar 发布）已实现自动化。要启用它，只需在您的构建中应用 com.gradleup.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 = file('../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/plugin/<your-plugin-id> 形式的 URL 中找到其使用说明。例如，Greeting 插件示例已在门户上，网址为 https://plugins.gradle.org/plugin/org.example.greeting。

在没有 Gradle 插件门户的情况下发布插件

如果您的插件是在没有使用 Java Gradle Plugin Development 插件的情况下发布的，则发布将缺少 Plugin Marker Artifact，这是插件 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}")
        }
    }
}

此页是否对您有帮助？