发布自己的jar包到Maven中央仓库

1,458 阅读10分钟

Maven仍然是目前使用人数很多的、非常受欢迎的项目构建工具。其方便之处在于:我们只需在配置文件pom.xml中引入依赖和插件,他就可以自动从中央仓库下载、配置并运行程序。不过假设我们自己写了一个jar外部包,想放到Maven中央仓库并使得别人和我们自己使用的时候更加方便,应该怎么做呢?

1,第一次发布时

在第一次发布时,我们首先要到Sonatype中央仓库注册账户以及命名空间,然后进行一些准备工作。

(1) 注册账户

进入Sonatype中央仓库官网:传送门

点击右上角Sign In按钮:

image.png

点击Sign up注册:

image.png

填写用户名,邮箱以及密码即可:

image.png

注册完成后,你的邮箱会收到一封验证邮件,点击其中的连接完成邮箱验证,登录即可。

(2) 注册命名空间

主页登录后,点击右上角你的头像-View Namespaces按钮:

image.png

点击Add Namespace按钮:

image.png

在下面填入你的命名空间:

image.png

需要注意的是,命名空间通常指的是你的项目的groupId,为你的域名或者Github或者Gitee仓库主页地址相关:

  • 如果你的Github主页地址为:github.com/swsk33,那么命名空间就是:io.github.swsk33
  • 如果是Gitee主页地址:gitee.com/swsk33,那么命名空间就应该是:io.gitee.swsk33

其余的同理,基本上都是类似于io.github.你的用户名形式。

如果你是使用自己的域名,比如swsk33-site.top,那么命名空间就应该是:top.swsk33-site

以Gitee为例,我们根据自己的用户名添加Gitee的命名空间,添加后如下图:

image.png

点击Verify Namespace按钮,它会弹出验证命名空间的步骤:

image.png

意思是让你登录你的Gitee账户并在Gitee上面创建一个公开仓库,仓库名(路径)就是上面的验证密钥名。

点击这个按钮复制密钥:

image.png

然后在Gitee上创建公开仓库:

image.png

创建完成,回到Sonatype账户中点击验证:

image.png

然后现在显示正在验证:

image.png

等待一段时间,刷新页面,如下图显示已完成验证则验证成功:

image.png

到此,我们就完成了使用自己的公开仓库创建命名空间并验证,如果说使用域名验证也是类似,只不过是需要登录你的域名解析网站,并给你的域名创建一个TXT记录,使用上述验证密钥作为值。

验证完成之后,你就可以删除刚刚用于验证的公开仓库或者是你的域名的TXT记录了!

(3) 生成用户Token并配置到Maven

同样地点击右上角头像-View Account按钮:

image.png

点击Generate User Token按钮:

image.png

image.png

然后会得到一个Token用户名和密码,将其复制到一个地方保存起来:

image.png

需要注意的是,关闭此窗口后以后就不能再看到Token了,除非重新生成,因此大家一定要先将其复制并保存。

然后进入我们的Maven安装目录,编辑目录里面的conf文件夹里面的settings.xml文件,找到里面的servers标签,并在其中添加如下内容将上述的Token用户名和密码配置进去:

<server>
	<id>central</id>
	<username>你的Token用户名</username>
	<password>你的Token密码</password>
</server>

到此,我们的Maven的上传Token也配置完成了!

(4) 生成GPG密钥对

由于后续发布项目时,需要使用GPG插件进行签名,因此我们还需要先在本地生成一个GPG密钥对。

在Windows操作系统上,只要安装了Git就可以使用gpg命令了!

右键打开Git Bash输入生成秘钥命令:

gpg --gen-key

然后会提示要你输入姓名和邮箱地址:

image.png

输入完成,会弹出个窗口让你设置这个秘钥的密码并确认:

image.png

自己设定一个密码并牢记,因为后面要用到这个密码的。

然后输入命令查询已经生成的秘钥:

gpg --list-keys

pub字段下面有一个十六进制数,那就是这个秘钥的ID。

image.png

然后我们要把这个秘钥上传至公钥服务器,使用如下命令:

gpg --keyserver keyserver.ubuntu.com --send-keys 秘钥ID

秘钥ID就是我们刚刚gpg --list-keys命令查到的自己的秘钥的ID,复制过去即可。

然后验证是否成功地上传到了服务器:

gpg --keyserver keyserver.ubuntu.com --recv-keys 秘钥ID

如果两条命令执行输出结果都如下说明成功:

image.png

这样,就完成了秘钥的配置了。

2,配置我们的项目并上传

现在我们可以上传项目了,不过发布到中央仓库的项目需要满足下列全部要求

  • 正确的工件坐标:即groupId必须和我们上述建立的Namespace一致,artifactId通常是项目本身名称,建议使用小写横杠命名法,例如sql-initialize-demo
  • 足够的元数据信息:即我们发布的项目的pom.xml中必须还要有name字段表示项目名称、description表示项目描述以及url表示项目地址
  • 许可证信息pom.xml中需要有licenses字段声明项目许可证
  • 开发者信息:需要有developers字段声明开发者信息例如开发者姓名、邮箱等
  • 代码仓库信息:需要有scm字段声明仓库源代码地址等信息
  • Javadoc和源代码:发布的项目中除了jar包本身,还需要有源代码和Javadoc包,不过这些借助maven-source-pluginmaven-javadoc-plugin插件在构建时自动生成即可,无需我们手动生成
  • 使用GPG密钥签名:上述我们配置了GPG密钥对,因此项目生成的文件还需要使用GPG密钥签名,不过我们借助maven-gpg-plugin插件在构建项目时自动进行签名即可,无需我们手动进行签名操作,不过需要注意的是要保证前面已经正确地声明了GPG密钥对,以及gpg命令时可用的

根据上述所有要求,我们配置我们要发布的项目的pom.xml如下形式即可:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<!-- 工件坐标,groupId必须和你申请时的一致 -->
	<groupId>组id</groupId>
	<artifactId>工件id</artifactId>
	<version>版本</version>
	<!-- 其余信息,自己填 -->
	<packaging>jar</packaging>
	<name>项目名</name>
	<description>描述</description>
	<url>项目地址</url>

	<!-- 项目设定 -->
	<properties>
		<java.version>1.8</java.version>
		<maven.compiler.source>${java.version}</maven.compiler.source>
		<maven.compiler.target>${java.version}</maven.compiler.target>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
	</properties>

	<!-- 许可证信息,这里是Apache 2.0的许可证,大家根据实际情况修改 -->
	<licenses>
		<license>
			<name>The Apache Software License, Version2.0</name>
			<url>https://www.apache.org/licenses/</url>
			<distribution>repo</distribution>
		</license>
	</licenses>

	<!-- 仓库信息,根据实际情况修改 -->
	<scm>
		<url>项目git仓库地址</url>
		<connection>项目git克隆地址</connection>
		<developerConnection>项目git仓库地址</developerConnection>
	</scm>

	<!-- 开发者信息,根据实际情况修改 -->
	<developers>
		<developer>
			<name>开发者名</name>
			<email>邮箱</email>
			<url>开发者主页</url>
		</developer>
	</developers>

	<build>
		<!-- 下列插件是发布到中央仓库所需要的,已配置好无需修改 -->
		<plugins>
			<!-- Sonatype中央仓库发布插件 -->
			<plugin>
				<groupId>org.sonatype.central</groupId>
				<artifactId>central-publishing-maven-plugin</artifactId>
				<version>0.8.0</version>
				<extensions>true</extensions>
				<configuration>
					<publishingServerId>central</publishingServerId>
				</configuration>
			</plugin>

			<!-- 源码生成插件 -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-source-plugin</artifactId>
				<version>3.3.1</version>
				<executions>
					<execution>
						<id>attach-sources</id>
						<goals>
							<goal>jar-no-fork</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

			<!-- Javadoc文档生成插件 -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-javadoc-plugin</artifactId>
				<version>3.11.2</version>
				<configuration>
					<show>private</show>
					<nohelp>true</nohelp>
				</configuration>
				<executions>
					<execution>
						<id>attach-javadocs</id>
						<goals>
							<goal>jar</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

			<!-- GPG签名插件 -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-gpg-plugin</artifactId>
				<version>3.2.7</version>
				<executions>
					<execution>
						<id>sign-artifacts</id>
						<phase>verify</phase>
						<goals>
							<goal>sign</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
</project>

简单的说一下这个配置文件:

  • groupId 必须就是我们刚刚创建的groupId,包名自己取
  • version 是应用版本,注意版本里面不要带有-SNAPSHOT字样,否则上传后可能无法在仓库找到并发布
  • urlnamedescription 是项目网址、名称和描述,这三者都是必须要的,缺一不可,否则上传项目是无法通过校验的
  • licensesdevelopersscm 这个也是必须的,根据自己的实际情况填写
  • build 部分是发布项目必要的一些插件,已经在上面的配置文件中配置好了,不用改变了,作用见上面的注释
  • central-publishing-maven-plugin插件配置中有publishingServerId这一项,这一项表示发布服务器id,该项需要和我们前面在Maven中配置的Token信息(Maven安装目录下conf/settings.xml中配置的server节点)中的id的值一致,由于前面我们配置的server节点idcentral,因此这里插件配置中的服务器id也是central

上面给出的示例,大家可以全部复制作为一个模板去使用,自己进行修改其中的内容,如果你是Maven多模块项目,则推荐将这些信息配置在父模块中。

项目配置完成后,就可以将其发布了!在我们的项目文件夹下打开Git Bash或者其它终端,输入上传项目命令:

mvn clean deploy

执行过程中会弹出一个窗口要求输入秘钥密码,就是输入我们先开始生成秘钥时设置的秘钥密码:

image.png

等待上传,最后显示绿色的Build Success说明上传成功。

3,去仓库发布项目到Maven中央仓库

上面的步骤只是把项目上传到了Sonatype上了,还没有发布出去。

同样地点击右上角头像-View Deployments按钮:

image.png

在这里可以看到刚刚你上传的项目,上面显示VALIDATED说明我们的项目是符合发布要求的,可以发布了,点击Publish按钮即可:

image.png

需要注意的是,一旦你的项目发布到中央仓库,它将不可被删除或者修改,如果需要修改那么只能上传新的版本。如果发布之前检查到有问题,可以点击Drop删除然后重新通过mvn clean deploy上传。

等待一段时间,显示PUBLISHED则发布完成:

image.png

这时,我们就可以到中央仓库搜索到我们刚刚发布的项目了:

image.png

4,以后再发布的时候

以后发布项目,如果groupId不变的话,我们就不需要再去重新添加Namespace了,直接重复上述的第2、3部分完成上传和发布操作即可。

上述Maven安装目录下的settings.xml已经配置了servers,就不用再次配置了,秘钥也已经生成过了,也不需要再次生成了。不过如果更换了电脑,那就要重新配置Maven安装目录下的settings.xml并重新生成并上传秘钥了。

此外,建议更换电脑/重装系统之前,可以导出自己的GPG密钥对,然后在新电脑上导入,这样避免多次生成GPG密钥。

首先查看公钥和私钥ID:

# 查看公钥列表
gpg --list-keys

# 查看私钥列表
gpg --list-secret-keys

结果:

image-20250620145951582

通过下列命令导出:

# 导出公钥
gpg --export 秘钥ID > 输出文件

# 导出私钥
gpg --export-secret-keys 秘钥ID > 输出文件

可将密钥对备份,拷贝到新电脑上,然后使用下列命令导入:

# 导入公钥/私钥
gpg --import 公钥/私钥文件

导入私钥时,同样需要输入私钥密码,导入完成后,再发布jar则无需重复上传密钥对到密钥服务器。

5,参考文档

本文参考文献如下:

  • Sonatype中央仓库注册和命名空间添加:传送门
  • Sonatype项目发布要求:传送门
  • Sonatype配置GPG密钥指引:传送门
  • Sonatype发布Maven项目指引:传送门
  • Maven源码生成插件使用文档:传送门
  • Maven Javadoc插件使用文档:传送门
  • Maven GPG插件使用文档:传送门