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

本文详细介绍了将Maven项目部署到Maven中央仓库时，如何解决Javadoc和源码缺失的问题。核心在于正确配置maven-source-plugin、maven-javadoc-plugin以生成并附加相关JAR包，以及使用maven-gpg-plugin对构件进行签名，确保部署流程符合Sonatype要求，最终实现Javadoc和源码的完整上传与展示。

在将java项目发布到maven中央仓库（如通过sonatype ossrh）时，开发者常会遇到一个问题：项目成功部署后，但在ide中导入该依赖时，却无法查看其javadoc或源码。这通常不是因为javadoc没有生成，而是因为它们没有作为独立的jar包正确地附加到构件中，或者部署流程因缺少必要签名而失败。本教程将提供一个完整的解决方案，确保您的项目在部署后能够正确显示javadoc和源码。

Maven中央仓库部署的核心要求

要成功将项目部署到Maven中央仓库并确保Javadoc和源码可用，主要有以下几个关键点：

GPG签名: 所有部署到Maven中央仓库的构件都必须使用GPG（GNU Privacy Guard）进行数字签名，以验证发布者的身份和构件的完整性。
源码JAR包: 必须生成并上传包含项目源代码的JAR包（通常以-sources.jar结尾）。
Javadoc JAR包: 必须生成并上传包含项目Javadoc文档的JAR包（通常以-javadoc.jar结尾）。
POM文件: 必须包含完整的项目元数据。

1. 配置GPG密钥

GPG签名是部署到Sonatype OSSRH的强制要求。您需要先生成一对GPG密钥。

生成GPG密钥：

Windows用户: 可以使用Gpg4win工具。安装后，通过Kleopatra图形界面或命令行工具gpg.exe生成密钥对。
macOS/Linux用户: 可以直接使用GnuPG命令行工具。
```
gpg --full-generate-key
```
按照提示输入密钥类型、密钥大小、有效期、用户ID（姓名和邮箱）以及密码。

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

gpg --keyserver hkp://pool.sks-keyservers.net --send-keys <您的密钥ID>

2. POM.xml配置：确保源码、Javadoc和签名

这是解决Javadoc和源码缺失问题的核心步骤。在项目的pom.xml文件中，您需要添加或修改以下插件配置，确保在构建和部署过程中生成并附加源码JAR、Javadoc JAR，并对所有构件进行签名。


    
        
        
            maven-source-plugin
            3.2.1 
            
                
                    attach-sources
                    
                        jar-no-fork 
                    
                
            
        

        
        
            maven-javadoc-plugin
            3.4.1 
            
                
                    attach-javadocs
                    
                        jar
                    
                
            
            
                
                16
                
                
                
            
        

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

        
        
            org.apache.maven.plugins
            maven-compiler-plugin
            3.10.1
            
                16
                16

配置说明：

maven-source-plugin: 这个插件负责在构建过程中将项目的源代码打包成一个JAR文件（例如your-project-1.0-sources.jar）。attach-sources执行目标确保在package阶段之后，这个源码JAR会被附加到主构件上。
maven-javadoc-plugin: 这个插件负责生成项目的Javadoc文档，并将其打包成一个JAR文件（例如your-project-1.0-javadoc.jar）。attach-javadocs执行目标确保Javadoc JAR也被附加到主构件上。configuration中的标签应与您的项目JDK版本一致。
maven-gpg-plugin: 这个插件用于对所有生成的构件（主JAR、源码JAR、Javadoc JAR和POM文件）进行GPG签名。sign-artifacts执行目标配置它在Maven生命周期的verify阶段执行签名操作。当maven-deploy-plugin运行时，它会部署所有已签名的构件。

3. 配置分发管理

在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/

请确保这里的ossrh与您在~/.m2/settings.xml文件中配置的Sonatype认证服务器ID一致。

4. 执行部署命令

完成上述配置后，您可以通过以下Maven命令来执行部署：

mvn clean deploy

clean: 清理项目构建目录，确保从一个干净的状态开始构建。
deploy: 执行整个Maven构建生命周期，包括编译、测试、打包、安装，并最终将构件（包括主JAR、源码JAR、Javadoc JAR和POM文件及其GPG签名）上传到distributionManagement中定义的远程仓库。

在执行mvn deploy时，maven-gpg-plugin会提示您输入GPG密钥的密码。

5. Sonatype OSSRH仓库管理

部署成功后，构件会被上传到Sonatype OSSRH的临时（Staging）仓库。您需要登录到Sonatype Nexus Repository Manager UI（通常是https://s01.oss.sonatype.org/），进行以下操作：

查看Staging Repositories: 导航到"Staging Repositories"页面，找到您的项目对应的Staging仓库。
关闭Staging仓库: 确认所有构件都已正确上传且签名无误后，选择您的Staging仓库并点击"Close"按钮。这将触发一系列验证，如果一切正常，仓库将被关闭。
发布（Release）仓库: 成功关闭Staging仓库后，您可以选择该仓库并点击"Release"按钮，将其正式发布到Maven中央仓库。发布过程可能需要几分钟到几小时，之后您的项目就可以被全球开发者使用了。

总结与注意事项

GPG密钥是强制性的：任何部署到Maven中央仓库的构件都必须经过GPG签名。如果部署失败，首先检查GPG密钥是否已正确生成、配置并用于签名。
插件配置完整性：maven-source-plugin和maven-javadoc-plugin的executions配置是确保源码和Javadoc JAR被附加的关键。
mvn clean deploy：这是一个完整的部署命令，确保所有生命周期阶段都被执行，包括签名。
Sonatype OSSRH操作：部署到Staging仓库后，务必在Sonatype UI中手动关闭并发布仓库。
IDE缓存：在发布新版本后，如果您的IDE（如IntelliJ IDEA）仍然无法显示Javadoc或源码，请尝试清理IDE缓存并重新导入Maven项目。

通过遵循本教程中的步骤，您将能够成功地将您的Maven项目部署到Maven中央仓库，并确保所有用户都能方便地访问其Javadoc文档和源代码。