发布插件是使其可供他人使用的主要方式。虽然你可以发布到私有仓库以限制访问,但发布到 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
文件中
plugins {
id("com.gradle.plugin-publish") version "1.2.1"
}
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
插件。
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)
}
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
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>"
}
}
}
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 插件 的配置。
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"
}
}
}
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
插件即可。
发布插件
如果你有兴趣发布你的插件以供更广泛的 Gradle 社区使用,你可以将其发布到 Gradle 插件门户。该网站提供搜索和收集 Gradle 社区贡献的插件信息的功能。请参阅关于如何在该网站上发布插件的相应章节。
本地发布
要检查你发布的插件 artifact 的外观或仅在本地或公司内部使用它,你可以将其发布到任何 Maven 仓库,包括本地文件夹。你只需配置用于发布的仓库。然后,你可以运行 publish
任务将你的插件发布到你定义的所有仓库(但不包括 Gradle 插件门户)。
publishing {
repositories {
maven {
name = "localPluginRepository"
url = uri("../local-plugin-repository")
}
}
}
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 {}
块,如下所示。
resolutionStrategy {
eachPlugin {
if (requested.id.namespace == "org.example") {
useModule("org.example:custom-plugin:${requested.version}")
}
}
}
resolutionStrategy {
eachPlugin {
if (requested.id.namespace == 'org.example') {
useModule("org.example:custom-plugin:${requested.version}")
}
}
}