在将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（姓名和邮箱）以及密码。
立即学习“Java免费学习笔记（深入）”；
生成密钥后，您可能需要将公钥发布到密钥服务器，以便其他人可以验证您的签名。
gpg --keyserver hkp://pool.sks-keyservers.net --send-keys <您的密钥ID>
2. POM.xml配置：确保源码、Javadoc和签名
这是解决Javadoc和源码缺失问题的核心步骤。在项目的pom.xml文件中，您需要添加或修改以下插件配置，确保在构建和部署过程中生成并附加源码JAR、Javadoc JAR，并对所有构件进行签名。
<build>
<plugins>
<!-- Maven Source Plugin: 附加源码JAR包 -->
<plugin>
<artifactId>maven-source-plugin</artifactId>
<version>3.2.1</version> <!-- 推荐使用最新稳定版本 -->
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal> <!-- 使用jar-no-fork避免重复构建 -->
</goals>
</execution>
</executions>
</plugin>
<!-- Maven Javadoc Plugin: 附加Javadoc JAR包 -->
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.1</version> <!-- 推荐使用最新稳定版本 -->
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- 指定JavaDoc的源版本，与项目保持一致 -->
<source>16</source>
<!-- 如果有私有或内部API，可以配置跳过错误 -->
<!-- <failOnError>false</failOnError> -->
<!-- <doclint>none</doclint> -->
</configuration>
</plugin>
<!-- Maven GPG Plugin: 对构件进行签名 -->
<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> <!-- 在verify阶段执行签名 -->
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- 其他构建插件，例如编译器插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.10.1</version>
<configuration>
<source>16</source>
<target>16</target>
</configuration>
</plugin>
</plugins>
</build>配置说明：
- 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中的<source>标签应与您的项目JDK版本一致。
- maven-gpg-plugin: 这个插件用于对所有生成的构件（主JAR、源码JAR、Javadoc JAR和POM文件）进行GPG签名。sign-artifacts执行目标配置它在Maven生命周期的verify阶段执行签名操作。当maven-deploy-plugin运行时，它会部署所有已签名的构件。
3. 配置分发管理
在pom.xml中，您还需要定义distributionManagement部分，指向Sonatype OSSRH的快照和发布仓库。
<distributionManagement>
<snapshotRepository>
<id>ossrh</id>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>ossrh</id>
<url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>请确保这里的<id>ossrh</id>与您在~/.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文档和源代码。
