贡献你的代码,将 jar 包发布到 Maven 中央仓库以及常见错误的解决办法

前几天将自己的日志工具发布到了Maven中央仓库中。这个工具本省没有多少技术含量,因为是修改别人的源代码实现的,但是将jar发布到Maven仓库却收获颇丰,因为网上有些教程过时了,在此分享下自己发布jar包的过程以及遇到的坑。我的项目时开源在Github上的,所以都是以Github为例来讲解的。

两个重要网址

因为后面会一直用到这两个网址,所以在这里着重介绍下,因为自己当初发布的时候一直没弄明白两个网站有什么作用。

  • Issues

    这个网站的主要作用就是添加自己发布jar包详情的网站,我们填写的东西叫做issue,在后面会讲解详细的操作。

  • OSS
    这个网站主要是用来保存我们上传的jar包,相当于一个仓库,我们会将自己的jar包先上传到该网址。

上述两个网址都属于Sonatype,因为中央仓库的服务是由Sonatype提供的,Sonatype的账号在上述两个网站中可以通用。

配置自己项目的POM文件

这个配置很重要,因为这涉及到你项目的相关信息,一般请按真实情况填写。
* 将你项目的parent设置为sonatype,因为Maven项目具有继承性,所以这样做可以节省你的配置信息。

<parent>
<groupId>org.sonatype.oss</groupId>
<artifactId>oss-parent</artifactId>
<version>7</version>
</parent>

  • 添加licenses信息,根据你的开源协议自行选择,例:
    <licenses>
          <license>
              <name>The Apache Software License, Version 2.0</name>
              <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
              <distribution>repo</distribution>
          </license>
      </licenses>
    
  • 添加scm,这个scm就是你也源代码仓库的一些信息,例:
    <scm>
          <tag>master</tag>
          <url>https://github.com/gh351135612/logger-sc.git</url>
      </scm>
    
  • 配置developers,根据你项目组的成员来添加
    <developers>
          <developer>
              <name>Shannon Chen</name>
              <email>shannonc@163.com</email>
          </developer>
      </developers>
    
  • 配置自身项目,这里主要是groupId,artifactId,version
    <groupId>com.github.gh351135612</groupId>
      <artifactId>logger-sc</artifactId>
      <version>1.1</version>
    

注:这里需要说明一下的是version这个配置,在你正式发布时不要在后面添加"SNOPSHOT"这种新式的版本号,具体原因在使用OSS的时候讲解

例如:

<version>1.0-SNAPSHOT</version>

创建Issues

这里假设已经创建好Sonatype的账号并登录了Issues

上面表单有几个地方需要说明一下,红色星号的是必填项,其中Project和Issue Type不要选错了,按照我截图的样式选择。
* Summary: 这里填写我们项目的名称,比如我的是logger-sc
* Description: 项目的描述信息,这个不是必填项,用户可以自行选择
* Attachment: 这个配置与后面的Group Id有关,如果我们的Group Id中的域名是私有的网站,需要提供域名的证书,证明该网站属于你。我这里的Group Id使用的Github的域名,所以不需要提供。
* Group Id: 这里填写你的域名,如果你的项目托管在Github上,你可以按照我的这种形式填写:com.github.gh351135612,后面的gh351135612是你Github的用户名,根据实际情况填写。
* Project URL: 你项目的主页,我的在Github上,所以是:https://github.com/gh351135612/logger-sc
* SCM url: 这个填写你项目的Git地址,如:https://github.com/gh351135612/logger-sc.git
* Username(s): 这个可以填写你Sonatype的用户名
* Already Synced to Central: 这个配置还没弄清有什么作用,我是按照默认配置‘No’来配置的
注:上述的信息其实就是你在POM中配置的,千万不要填错了,不然后面会报各种错误。虽然有人会用英文提醒你,但是排查起来还是比较困难,因为Sonatype的教程都是英文的,国内的教程也不多。
如果你填写正确很快会收到如下的comment,如果不正确客服人员会告诉你原因,按照提示进行修改就可以了。


配置本地Maven的setting.xml文件

因为我的是Windows系统,所以路径在这里,其它系统的用户可以自行百度。

配置servers节点下的server

上面两个server的用户名和密码都是你在Sonatype账户的信息,一个账户对应多个server。至于为什么这样配置是由原因的,我之前在网上找的教程可能是比较老与我的配置不一样,我按照老的配置结果一直报错。这里的server必须与POM中的distrubitionManagement中repository的id对应,因为我们项目的Parent是sonatype,所以我们可以在Parent中的POM中看到这个配置。

我们在查阅网上教程的时候最好关注一下它的时效性,如果能知其原理就不会被过时的教程给误导了。

使用Gpg生成密钥

因为我们的jar包是要发布到网上的,为了验证jar包的身份,我们需要使用Gpg对jar包进行签名。我这里只是简单使用了下Gpg,并没有做过多的了解,这个因该也分私钥与公钥。但是这个工具的在Windows和Mac系统下的命令不一样,如果Windows用户使用不需要额外的配置,Mac用户需要配置下POM文件。Gpg生成密钥很简单,其中会让你输入用户名,邮箱,密码之类的信息,按照实际情况填写就可以了,只是密码千万不要忘记了,后面发布jar包时会用到。这里只简单介绍一下相关命令:

  • 生成密钥
gpg --gen-key
  • 查看密钥
gpg --list-keys

如果你的密钥生成好了,还需要将其发布到公网的服务器上,这里猜想可能是将公钥发布到网上,命令如下:

gpg --keyserver hkp://keyserver.ubuntu.com:11371 --send-keys 8C473F5C

后面的8C473F5C就是你密钥的id,根据你自己的id填写即可,如果发现上述keyserver无法连接,可以百度其它服务器应该也是可行的,我这里碰到过这种情况,上面这个服务器应该没有这个问题。

mac系统使用Gpg:

因为mac下gpg命令变成了gpg2,而maven中默认的命令配置的是gpg,所以需要配置下Maven的setting.xml文件

<settings>
  <profiles>
    <profile>
      <id>gpg</id>
      <properties>
        <gpg.executable>gpg2</gpg.executable>
        <gpg.passphrase>mypassphrase</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>gpg</activeProfile>
  </activeProfiles>
</settings>

上面的配置本人没有尝试,如果不行用户可以再搜索其它教程


将jar包发布到OSS

前面的准备工作做好了之后,下面这些步骤就简单多了,输入如下命令就行部署:

mvn clean deploy -P sonatype-oss-release

在命令执行的过程中会让用户输入密码,也就是你Gpg生成密钥的时候输入的密码。这个步骤很容易部署出错,我当初部署的时候试了好多次,这里列举下我出错的原因:
* 出现401认证失败的错误
可能是Maven的settings.xml配置有误,比如server的id不正确,用户名密码不匹配
* 出现权限错误
可能是你POM中的GroupId与Issues中填写的GroupId不匹配

** 如果出现其它错误请Google或者问Sonatype的客服吧,前提是你的英语还可以,不然还是挺抓狂的,百度基本搜索不出来有价值的信息**

在OSS中发布自己的jar包

如果上面的部署成功了,我们正常情况下我们就可以在OSS中搜索到自己的jar包,如何搜索情况下面的截图:

正常情况下你是可以在这里搜索到的,并且很快就能搜索到,如果你搜索不到可能是项目的version中包含‘SNAPSHOT’的后缀。因为这个表示并不表示是要发布的版本,我们使用别人的jar包时经常会看到release的字样,这才是要发布的版本号后缀,如果你不带release也是可以的。具体原因请看Sonatype客服给我的回复:

如果你可以搜索到自己的项目了那就先close自己的项目,然后release.这两部很简单,找到对应的按钮就可以操作了,操作过程中会让你填写你写描述信息,随便填写即可,没有什么限制。如果没有搜索到也不要傻等了,肯定是步骤有误,排查错误重新尝试。

注:close和release操作有一定的延时,可以等待几分钟再刷新看状态是否发生变化,如果没有变化可以查看具体信息看看是否有错误产生


将jar包同步到中央仓库

如果你上面的步骤都没有遇到什么问题,那么你只需要在你项目的Issues中给客服回复一条Comment就可以了。

上面客服人员会回复你,你的组件会在十分钟内推送到中央仓库,但是你的项目会在两个小时之后才能在search.maven.org中被搜索到。

更新你的jar包

更新也很容易,按照部署的方式操作即可,只是不需要再回复客服消息了。如果你第一次同步到中央仓库成功,你可以关闭这个issue,因为它的使命已经完成了,issue就像一张登记表一样,只是在第一次进入时需要使用。这里需要说明的是如果你的版本号发生变化就会以新版本发布,如果版本号不发生变化就会覆盖掉之前的版本。


将jar包发布到中央仓库操作还是挺麻烦的,Android的lib使用jcenter发布好像便捷一些。如果你是Android的lib发布jar或者aar还是选择jcenter吧。

发表评论

电子邮件地址不会被公开。 必填项已用*标注