在将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可以进行认证部署。
立即学习“Java免费学习笔记（深入）”；
<!-- ~/.m2/settings.xml 或 Maven安装目录/conf/settings.xml --> <settings> <servers> <server> <id>ossrh</id> <username>您的Sonatype用户名</username> <password>您的Sonatype密码</password> </server> </servers> <!-- ... 其他配置 ... --> </settings>
2. 核心配置：确保Javadoc和源码上传
为了让Maven在部署时附加Javadoc和源码，您需要在项目的 pom.xml 文件中配置 maven-source-plugin 和 maven-javadoc-plugin。关键在于为这两个插件添加 executions 配置，确保它们的 jar 目标在适当的生命周期阶段被执行。
<build>
<plugins>
<!-- 配置maven-source-plugin以生成并附加源码jar包 -->
<plugin>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- 配置maven-javadoc-plugin以生成并附加Javadoc jar包 -->
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- 指定Java源版本，确保Javadoc兼容性 -->
<source>16</source>
<!-- 可选：如果Javadoc有警告，部署时可能失败，这里可以忽略 -->
<!-- <failOnError>false</failOnError> -->
</configuration>
</plugin>
<!-- ... 其他插件，如maven-compiler-plugin等 ... -->
</plugins>
</build>说明：
- 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）。
- <configuration><source>16</source></configuration> 确保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 配置：
<build>
<plugins>
<!-- ... 前面配置的source和javadoc插件 ... -->
<!-- 配置maven-gpg-plugin以对所有构件进行GPG签名 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.5</version> <!-- 或更高版本，如1.6/3.0.1 -->
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase> <!-- 在verify阶段执行签名 -->
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>说明：
- maven-gpg-plugin 的 sign-artifacts 执行会在 verify 生命周期阶段对所有生成的构件（包括主jar、源码jar、Javadoc jar和POM文件）进行签名。
- phase 设置为 verify 确保在打包和安装之后，但在部署之前进行签名。
4. 部署管理配置
在 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 必须与您在 settings.xml 中配置的 <server><id> 保持一致，以便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中央仓库进行访问了。
6. 注意事项与总结
- GPG密钥密码：请确保您在 mvn deploy 过程中输入的GPG密码是正确的。错误的密码会导致签名失败，进而使整个部署过程失败。
- 插件版本：确保您使用的Maven插件版本是稳定且兼容的。
- 网络连接：部署过程需要稳定的网络连接来上传文件和与Sonatype OSSRH交互。
- 日志检查：在 mvn deploy 过程中，仔细检查控制台输出的日志，任何错误或警告都可能指示配置问题。
- 验证：在发布到中央仓库后，建议您在新项目中使用您的依赖，并验证Javadoc和源码是否能够正确显示。
通过遵循上述详细步骤，您将能够成功地将您的Maven项目连同其Javadoc和源码一起发布到Maven中央仓库，为其他开发者提供一个完整且专业的开源库。
