将插件发布到 Gradle 插件门户

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

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

前提条件

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

尝试发布此插件将安全地因权限错误而失败，因此不必担心用一个简单的示例插件弄乱 Gradle 插件门户。

账户设置

在发布插件之前，你必须在 Gradle 插件门户上创建一个账户。按照注册页面上的说明创建账户，并从你的个人资料页面的“API Keys”选项卡获取 API 密钥。

将你的 API 密钥存储在 Gradle 配置中 (gradle.publish.key 和 gradle.publish.secret)，或者使用像 Seauc Credentials plugin 或 Gradle Credentials plugin 这样的插件进行安全管理。

通常的做法是将文本复制并粘贴到你的 $HOME/.gradle/gradle.properties 文件中，但你也可以将其放置在任何其他有效位置。插件所需的只是在执行相应的插件门户任务时，gradle.publish.key 和 gradle.publish.secret 可作为项目属性使用。

如果你担心将凭据放在 gradle.properties 中，可以查看 Seauc Credentials plugin 或 Gradle Credentials plugin。

或者，你可以通过 GRADLE_PUBLISH_KEY 和 GRADLE_PUBLISH_SECRET 环境变量提供 API 密钥。这种方法可能适用于 CI/CD 流水线。

添加插件发布插件

要发布你的插件，请将 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 插件门户上找到 Plugin Publishing Plugin 的最新版本。

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

配置插件发布插件

在你的 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 插件门户的仓库中标识你为插件发布的 artifacts（jar 和元数据），并且应描述插件作者或插件所属的组织。
2	设置你的项目版本，它也将用作你的插件版本。
3	使用 Java Gradle 插件开发插件提供的 `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 插件相关的页面，你将看到指定的元数据显示方式。

源码和 Javadoc

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

对 Artifact 进行签名

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

Shadow 依赖项

从 Plugin Publish Plugin 1.0.0 版本开始，shadowing 你的插件依赖项（即，将其发布为 fat jar）已自动化。要启用它，只需要在你的构建中应用 com.gradleup.shadow 插件即可。

发布插件

如果你将插件内部发布供组织内部使用，可以像发布任何其他代码 artifact 一样发布它。请参阅关于发布 artifact 的 Ivy 和 Maven 章。

如果你有兴趣发布你的插件以供更广泛的 Gradle 社区使用，你可以将其发布到 Gradle 插件门户。该网站提供搜索和收集 Gradle 社区贡献的插件信息的功能。请参阅关于如何在该网站上发布插件的相应章节。

本地发布

要检查你发布的插件 artifact 的外观或仅在本地或公司内部使用它，你可以将其发布到任何 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 插件，你将遇到权限失败。这是预期的，并确保门户不会被多个实验性和重复的问候类型插件淹没。

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

使用已发布的插件

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

你的插件获批后，可以在格式为 https://plugins.gradle.org/plugin/<your-plugin-id> 的 URL 上找到使用说明。例如，Greeting 插件示例已在门户上，地址为 https://plugins.gradle.org/plugin/org.example.greeting。

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

如果你的插件未使用 Java Gradle 插件开发插件发布，则发布将缺少插件标记 Artifact，它是 plugins DSL 用于定位插件所需的。在这种情况下，在另一个项目中解析插件的推荐方法是将 resolutionStrategy 部分添加到项目的 settings 文件中的 pluginManagement {} 块，如下所示。

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}")
        }
    }
}

此页面有帮助吗？