Maven项目发布到中央仓库：确保Javadoc和源码正确上传的完整指南_技术教程

本教程详细阐述了Maven项目发布到中央仓库时，如何解决Javadoc和源码丢失的问题。文章将指导读者配置Maven Source Plugin、Javadoc Plugin和GPG Plugin，确保在部署过程中正确生成并上传源码包和Javadoc包，同时涵盖GPG密钥生成、Sonatype OSSRH部署流程及注意事项，旨在帮助开发者顺利发布符合规范的开源库。

在将java项目发布到maven中央仓库时，开发者经常会遇到一个常见问题：尽管项目本身成功部署，但使用者在ide中导入依赖后，却无法看到相应的javadoc文档或源码。这通常不是因为javadoc没有生成，而是因为在部署过程中，javadoc和源码的jar包没有被正确地附加并上传。此外，缺少gpg签名也是导致部署失败或不完整的关键因素。本文将提供一个全面的指南，帮助您解决这些问题，确保您的开源库能够以完整的形式（包含javadoc和源码）发布到maven中央仓库。

1. Maven中央仓库部署的前置条件

在深入配置之前，确保您已完成以下准备工作：

Sonatype OSSRH账户和项目创建：您需要在Sonatype JIRA上创建一个issue来申请您的groupId，并等待批准。
GPG密钥对：Maven中央仓库要求所有上传的构件都必须经过GPG签名。

Maven settings.xml 配置：配置您的Sonatype OSSRH凭据，以便Maven可以进行认证部署。



    
        
            ossrh
            您的Sonatype用户名
            您的Sonatype密码

2. 核心配置：确保Javadoc和源码上传

为了让Maven在部署时附加Javadoc和源码，您需要在项目的 pom.xml 文件中配置 maven-source-plugin 和 maven-javadoc-plugin。关键在于为这两个插件添加 executions 配置，确保它们的 jar 目标在适当的生命周期阶段被执行。


    
        
        
            maven-source-plugin
            
                
                    attach-sources
                    
                        jar
                    
                
            
        

        
        
            maven-javadoc-plugin
            
                
                    attach-javadocs
                    
                        jar
                    
                
            
            
                
                16

说明：

maven-source-plugin 的 attach-sources 执行将确保在构建过程中生成一个包含项目源码的jar包（例如 your-artifact-id-version-sources.jar）。
maven-javadoc-plugin 的 attach-javadocs 执行将生成一个包含项目Javadoc的jar包（例如 your-artifact-id-version-javadoc.jar）。
16 确保Javadoc工具使用指定的Java版本进行编译，这对于避免兼容性问题很重要。

3. GPG签名配置与密钥生成

Maven中央仓库要求所有上传的构件都必须进行GPG签名，这是确保构件完整性和来源可信度的重要步骤。

3.1 GPG密钥生成

如果您尚未拥有GPG密钥对，您需要先生成一个。

Windows用户：推荐使用 Gpg4win 工具，它提供图形界面，方便生成和管理密钥。
macOS/Linux用户：可以通过命令行工具 gpg 生成。打开终端并运行：
```
gpg --full-generate-key
```
按照提示选择密钥类型（通常是默认的RSA and RSA）、密钥长度（推荐4096位）、有效期，并输入您的姓名、电子邮件和密码。请务必记住您设置的密码，部署时会用到。

生成密钥后，您需要将其公钥发布到公共密钥服务器，以便其他人可以验证您的签名。

gpg --keyserver hkp://keyserver.ubuntu.com:80 --send-keys 您的GPG密钥ID

将您的GPG密钥ID 替换为您生成的密钥ID，可以通过 gpg --list-secret-keys 查看。

3.2 maven-gpg-plugin 配置

在 pom.xml 的 build 部分添加 maven-gpg-plugin 配置：


    
        

        
        
            org.apache.maven.plugins
            maven-gpg-plugin
            1.5 
            
                
                    sign-artifacts
                    verify 
                    
                        sign

说明：

maven-gpg-plugin 的 sign-artifacts 执行会在 verify 生命周期阶段对所有生成的构件（包括主jar、源码jar、Javadoc jar和POM文件）进行签名。
phase 设置为 verify 确保在打包和安装之后，但在部署之前进行签名。

4. 部署管理配置

在 pom.xml 中添加 distributionManagement 部分，指向Sonatype OSSRH的快照和发布仓库地址：


    
        ossrh
        https://s01.oss.sonatype.org/content/repositories/snapshots
    
    
        ossrh
        https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/

这里的 id 必须与您在 settings.xml 中配置的保持一致，以便Maven能够找到正确的认证信息。

5. 部署流程

完成上述所有配置后，您可以通过以下步骤进行部署：

执行部署命令：在项目根目录打开命令行，执行：
```
mvn clean deploy
```
在执行 deploy 命令时，maven-gpg-plugin 会要求您输入GPG密钥的密码。正确输入后，Maven会将主jar、源码jar、Javadoc jar以及它们的GPG签名文件（.asc）和POM文件上传到Sonatype OSSRH的临时（staging）仓库。
管理Sonatype OSSRH临时仓库：部署成功后，登录到Sonatype OSSRH界面（通常是 https://s01.oss.sonatype.org/#stagingRepositories）。
- 您会看到一个新创建的临时仓库，其中包含您上传的所有构件。
- 检查构件是否完整，确保有主jar、源码jar、Javadoc jar以及对应的 .asc 签名文件。
- 选择您的临时仓库，点击 "Close" 按钮。这会触发Sonatype对构件进行验证。如果所有验证（包括GPG签名）都通过，仓库状态将变为 "Closed"。
- 一旦仓库状态变为 "Closed"，您可以选择该仓库并点击 "Release" 按钮，将其发布到Maven中央仓库。这个过程可能需要一些时间（通常几分钟到几小时），之后您的构件就可以通过Maven中央仓库进行访问了。