Charming 的博客

如何发布项目到 Maven 中央仓库

在公司用 Maven 发布项目的时候,执行 mvn deploy 会将依赖上传到公司自己的 Maven 私服上,只有在 settings.xml 上配置了公司 Maven 私服地址才能够下载此依赖。但是其他的依赖如 guava 这些依赖无论是否配置公司 Maven 私服地址,都能够引用下载。那我能不能也写一个工具上传到这个地方,不需要配置 Maven 私服地址就能够使用呢?带着这个问题,我开始了我的探索历程。

找到真正的方法

  1. Google “maven deploy”,找到 Guide to uploading artifacts to the Central Repository
  2. 这篇文章大部分讲的是 Apache 开源软件如何发布到 Central Repository,也提到了其余开源项目如何发布——Open Source Software Repository Hosting (OSSRH)
  3. 锁定目标,就是这篇文章了,沉下心来看懂实践;

如何发布项目到 Maven Central Repository

以下所有步骤都提炼自 Open Source Software Repository Hosting (OSSRH),有条件的话尽量看原文。另外,如果以下步骤与原文不一样,请以原文为主。

〇、开始之前

在开始之前你需要有:

  • GitHub 账户;
  • GitHub Maven 项目;

一、注册 JIRA 账户

点击注册:https://issues.sonatype.org/secure/Signup!default.jspa

二、创建项目的 Issue

点击创建:https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134 ,表单中的一些说明请不要忽略。一下是注意事项:

  • Summary 建议填写 artifactId;
  • Group Id 要特别注意,最好与下面的项目主页地址差不多,比如 io.github.username 或者
    com.github.username 都是很容易审核通过的;如果你填写的是自己域名,比如我填写得是
    com.charmingoh,管理员会问你这个网站是不是你的,你需要向管理员说明;
  • Project URL 是项目主页,一般填写 GitHub 的项目主页,我填写的是:https://github.com/charmingoh/awesome-java-lib
  • SCM url 是项目的版本控制地址,我填写的是:https://github.com/charmingoh/awesome-java-lib.git

我的项目地址是:https://issues.sonatype.org/browse/OSSRH-28006

三、等待管理员审核

如果你发布项目的时候管理员在上班(美国),那么你的项目很快就会有审核消息,保持关注就行了。如果管理员有问题,需要在你创建的 Issue 详情下回复。

如果审核通过,管理员会回复:

Configuration has been prepared, now you can:
……

在等待的时间,可以执行第四步。

四、生成 PGP 签名

以下所有步骤都提炼自 Working with PGP Signatures,有条件的话尽量看原文。

  • 安装 GPG;
    • 可以在官方直接下载,http://www.gnupg.org/download/
    • 也可以用你喜欢的包管理工具下载,如 Ubuntu 下的 apt-get,CentOS 下的 yum,Mac 下的 Homebrew
    • 我是 Mac 用户,直接用 Homebrew,brew install gpg
    • 执行 gpg --version 或者 gpg2 --version 看是否安装成功;
  • 生成密钥;
    • 执行 gpg --gen-key
    • 两次回车:选择默认的 RSA and RSA2048bit
    • 选择密钥的有效期,我直接回车选择永久(官方建议 2 年及一下);
    • 填写你的名字、邮箱、Comment;
    • 输入 passphrase(记下来);

五、规范 pom.xml

以下所有步骤都提炼自 RequirementsDeploying to OSSRH with Apache Maven ,有条件的话尽量看原文。

开源软件发布到 Central Repository 需要将文件进行 PGP 签名,并且提供源代码、Java doc、项目元数据等,这些工作都大部分都在在 pom.xml 做,可参考以下 pom.xml:

pom.xml 要求:

  • 正确的 groupId / artifactId / version / packaging
  • 需要 name、description、url、developers 信息、SCM 信息
  • 需要开源许可证 licenses
  • 添加 distributionManagement

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    <distributionManagement>
    <snapshotRepository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </snapshotRepository>
    <repository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
    </distributionManagement>
  • settings.xml 配置 ossrh 的用户名和密码为步骤一注册的 JIRA 用户名和密码

    1
    2
    3
    4
    5
    6
    7
    8
    9
    <settings>
    <servers>
    <server>
    <id>ossrh</id>
    <username>your-jira-id</username>
    <password>your-jira-pwd</password>
    </server>
    </servers>
    </settings>
  • 添加 maven-source-pluginmaven-javadoc-plugin(最新版本到官网找)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    <build>
    <plugins>
    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.0.1</version>
    <executions>
    <execution>
    <id>attach-sources</id>
    <goals>
    <goal>jar-no-fork</goal>
    </goals>
    </execution>
    </executions>
    </plugin>
    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.4</version>
    <executions>
    <execution>
    <id>attach-javadocs</id>
    <goals>
    <goal>jar</goal>
    </goals>
    </execution>
    </executions>
    </plugin>
    </plugins>
    </build>
  • 添加签名插件 maven-gpg-plugin;

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    <build>
    <plugins>
    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-gpg-plugin</artifactId>
    <version>1.6</version>
    <executions>
    <execution>
    <id>sign-artifacts</id>
    <phase>verify</phase>
    <goals>
    <goal>sign</goal>
    </goals>
    </execution>
    </executions>
    </plugin>
    </plugins>
    </build>
  • 在 settings.xml 添加你的 passphrase(步骤四记住的);

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <settings>
    <profiles>
    <profile>
    <id>ossrh</id>
    <activation>
    <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
    <gpg.executable>gpg</gpg.executable> <!-- 可执行文件也可能是 gpg2 -->
    <gpg.passphrase>the_pass_phrase</gpg.passphrase>
    </properties>
    </profile>
    </profiles>
    </settings>
  • 添加 nexus-staging-maven-plugin

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <plugin>
    <groupId>org.sonatype.plugins</groupId>
    <artifactId>nexus-staging-maven-plugin</artifactId>
    <version>1.6.7</version>
    <extensions>true</extensions>
    <configuration>
    <serverId>ossrh</serverId>
    <nexusUrl>https://oss.sonatype.org/</nexusUrl>
    <autoReleaseAfterClose>true</autoReleaseAfterClose>
    </configuration>
    </plugin>

六、正式发布

此步骤必须建立在步骤三完成的基础上,即在 JIRA 发布的 Issue 必须被管理员审核通过。

  • 执行 mvn clean deploy
  • 在你创建的 Issue 下面回复管理员说你的软件发布了;
  • 等待管理员回复;
  • 无需等待可以在 https://oss.sonatype.org 上搜索到自己的项目;
  • 管理员回复后两个小时可以在 search.maven.org 上搜索到自己的项目,然后别人就无需额外配置 Maven 私服就能够使用你发布的软件了^_^

总结

这个过程折腾了挺久的,从一开始找的中文资料,再到后来找到官方文档沉下心来看,突然发现官方文档还是很容易看懂的。也体会到了官方文档的优势,毕竟是一手资源,官方肯定也会尽最大努力去让文档更加通熟易懂操作性强。一手资源时效性最强,而二手资源可能有些步骤不是最简单的或者配置不是最新的(包括本文也会有过时的时候)。所以还是持着这样一个态度:以官方文档资源为主,二手资源为辅。