1. 理解Maven中央仓库部署要求
将java库发布到maven中央仓库（如通过sonatype ossrh）不仅仅是上传项目的主jar包。为了提供完整的开发体验和满足仓库规范，通常需要提供以下构件：
- 主构件（Primary Artifact）: 编译后的项目JAR包。
- 源码构件（Sources Artifact）: 包含项目源代码的JAR包，通常命名为 *-sources.jar。这对于用户在IDE中查看源码、调试非常有用。
- Javadoc构件（Javadoc Artifact）: 包含项目API文档的JAR包，通常命名为 *-javadoc.jar。这是IDE显示Javadoc的关键。
- GPG签名构件（GPG Signature Artifacts）: 对上述所有构件（包括POM文件）生成的GPG签名文件，通常以 .asc 结尾。这是Sonatype OSSRH强制要求的安全措施，用于验证构件的完整性和来源。
如果缺少上述任何一个构件（特别是源码、Javadoc或GPG签名），部署到Sonatype OSSRH的暂存仓库时可能会失败，或者即使部署成功，用户在IDE中导入依赖时也无法看到Javadoc和源码。
2. 配置Maven插件生成并附加构件
要确保源码、Javadoc和GPG签名构件被正确生成并附加到部署中，需要在项目的 pom.xml 文件中配置相应的Maven插件。
2.1 源码插件配置 (maven-source-plugin)
maven-source-plugin 用于生成包含项目源代码的JAR包。关键在于将其配置为在Maven的生命周期中执行 attach-sources 目标。
<plugin>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal> <!-- 推荐使用jar-no-fork，避免不必要的fork -->
</goals>
</execution>
</executions>
</plugin>注意: jar-no-fork 目标通常在 package 阶段执行，它会在不创建新进程的情况下生成源码JAR。
立即学习“Java免费学习笔记（深入）”；
2.2 Javadoc插件配置 (maven-javadoc-plugin)
maven-javadoc-plugin 用于生成包含项目API文档的JAR包。同样，需要配置其在Maven生命周期中执行 attach-javadocs 目标。
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- 根据项目使用的Java版本配置 -->
<source>16</source>
<!-- 如果Javadoc生成有警告或错误，可配置忽略 -->
<!-- <failOnError>false</failOnError> -->
<!-- <doclint>none</doclint> -->
</configuration>
</plugin>注意: jar 目标通常在 package 阶段执行，它会生成Javadoc JAR。source 配置应与项目编译时使用的JDK版本匹配。
2.3 GPG签名插件配置 (maven-gpg-plugin)
maven-gpg-plugin 用于对所有待部署的构件进行GPG签名。这是Sonatype OSSRH强制要求的，如果缺少签名，部署到暂存仓库会失败。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.6</version> <!-- 推荐使用较新版本，如1.6或更高 -->
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase> <!-- 通常在verify阶段执行签名 -->
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>注意:
- version 建议使用最新稳定版，例如 1.6 或更高。
- phase 设置为 verify 确保在打包和测试之后、部署之前进行签名。
- 执行 mvn deploy 时，Maven会自动提示输入GPG密钥的密码。
3. 生成并配置GPG密钥
在能够使用 maven-gpg-plugin 之前，你需要在本地系统上生成一个GPG密钥对。
3.1 GPG密钥生成
- 安装GPG工具:
-
生成密钥: 打开命令行或Gpg4win的Kleopatra工具，执行以下命令：
gpg --full-generate-key
按照提示选择密钥类型（通常是RSA and RSA）、密钥长度（推荐4096位）、有效期（无有效期或设置一个较长的时间），然后输入你的真实姓名、电子邮件地址和注释。最后，设置一个强密码来保护你的私钥。
- 获取密钥ID: 生成完成后，可以使用 gpg --list-secret-keys --keyid-format LONG 命令查看你的私钥，其中会包含一个长格式的密钥ID（例如 0xABCDEF1234567890）。
3.2 Maven settings.xml 配置（可选但推荐）
虽然 maven-gpg-plugin 在执行 sign 目标时会直接从GPG代理获取密钥，但为了更明确地指定使用的密钥，可以在Maven的 settings.xml 文件中配置。这在某些自动化环境中特别有用。
在 ~/.m2/settings.xml 文件中添加 profile：
<settings>
<!-- ... 其他配置 ... -->
<profiles>
<profile>
<id>gpg</id>
<properties>
<!-- 替换为你的GPG密钥ID -->
<gpg.keyname>你的GPG密钥ID</gpg.keyname>
<!-- 如果你的GPG密钥有密码，可以在这里配置，但通常不推荐在settings.xml中明文存储密码 -->
<!-- <gpg.passphrase>你的GPG密钥密码</gpg.passphrase> -->
</properties>
</profile>
</profiles>
<activeProfiles>
<activeProfile>gpg</activeProfile>
</activeProfiles>
</settings>警告: 在 settings.xml 中明文存储GPG密码存在安全风险。通常建议在部署时手动输入密码，或使用Maven加密密码功能。
4. 配置 distributionManagement
distributionManagement 部分定义了项目部署到远程仓库的信息。对于Sonatype OSSRH，你需要配置快照仓库和发布仓库的URL。
<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) 必须与你在 ~/.m2/settings.xml 中配置的服务器认证信息（server 块）的 id 匹配。
5. 执行部署流程
完成上述配置后，可以执行部署命令：
-
清理并部署:
mvn clean deploy
执行此命令时，Maven会：
- 清理项目。
- 编译、测试、打包主JAR。
- 根据插件配置生成源码JAR (*-sources.jar)。
- 根据插件配置生成Javadoc JAR (*-javadoc.jar)。
- 使用GPG密钥对所有构件（包括POM文件）进行签名，并生成 .asc 签名文件。
- 将所有生成的构件及其签名文件上传到 distributionManagement 中配置的仓库（对于发布版本是Sonatype的暂存仓库）。
-
Sonatype OSSRH暂存仓库操作:
- 部署成功后，登录到 Sonatype OSSRH 的 Nexus 界面（通常是 https://s01.oss.sonatype.org/#stagingRepositories）。
- 在 "Staging Repositories" 区域，你会看到一个新创建的暂存仓库，其中包含你刚刚部署的所有构件。
- 关闭（Close）暂存仓库: 选中你的暂存仓库，点击 "Close" 按钮。这一步会执行一系列验证，确保所有必要的构件（包括签名、源码、Javadoc）都已上传且有效。如果缺少任何强制构件或签名不正确，关闭操作会失败，并显示错误信息。
- 发布（Release）暂存仓库: 成功关闭后，再次选中该暂存仓库，点击 "Release" 按钮。这将把你的构件从暂存仓库移动到Maven中央仓库，通常在几小时内同步到全球的Maven镜像。
6. 常见问题与排查
-
GPG签名失败或提示缺少密钥:
- 确保已正确安装GPG工具并生成了密钥。
- 确认在 mvn deploy 过程中输入了正确的GPG密钥密码。
- 检查 maven-gpg-plugin 的配置是否正确，特别是 phase 和 goals。
- 如果使用 gpg.keyname，请确保其值与你的GPG密钥ID匹配。
-
Sonatype暂存仓库关闭失败:
- 这是最常见的问题，通常意味着缺少了强制构件。
- 仔细检查错误日志，它会明确指出缺少了什么（例如 *-sources.jar, *-javadoc.jar, *.asc 签名文件）。
- 检查 maven-source-plugin 和 maven-javadoc-plugin 的 executions 配置是否正确，确保 attach-sources 和 attach-javadocs 目标被执行。
- 确认 maven-gpg-plugin 已正确配置并成功执行了签名。
- 确保你的 pom.xml 中有 name, description, url, licenses, developers, scm 等必要信息，这些也是Sonatype的要求。
-
IDE中仍看不到Javadoc:
- 确保你的项目依赖已正确导入。
- 在IDE（如IntelliJ IDEA）中，可能需要手动刷新Maven依赖或重新导入项目。
- 确认中央仓库中的构件确实包含 *-javadoc.jar 文件。如果怀疑，可以尝试直接从Maven中央仓库下载你的构件，手动检查其内容。
总结
成功将Maven项目发布到中央仓库，并确保Javadoc和源码可供用户使用，需要对Maven的构建生命周期、插件配置和Sonatype OSSRH的部署流程有清晰的理解。核心在于：正确配置 maven-source-plugin 和 maven-javadoc-plugin 以生成并附加源码和Javadoc JAR包，并使用 maven-gpg-plugin 对所有构件进行签名。 遵循这些步骤，并仔细处理Sonatype的暂存仓库验证，将确保你的项目以完整的姿态呈现在全球开发者面前。
