Maven项目部署至中央仓库：确保Javadoc和源码完整发布的指南

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密钥生成

1. 安装GPG工具:
   • Windows: 推荐安装 Gpg4win。
   • macOS: 可以通过 Homebrew 安装 brew install gnupg。
   • Linux: 大多数发行版都预装了 gnupg 或可以通过包管理器安装。
2. 生成密钥: 打开命令行或Gpg4win的Kleopatra工具，执行以下命令：

   gpg --full-generate-key

   登录后复制

   按照提示选择密钥类型（通常是RSA and RSA）、密钥长度（推荐4096位）、有效期（无有效期或设置一个较长的时间），然后输入你的真实姓名、电子邮件地址和注释。最后，设置一个强密码来保护你的私钥。

3. 获取密钥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：

码上飞

码上飞（CodeFlying） 是一款AI自动化开发平台，通过自然语言描述即可自动生成完整应用程序。

138

查看详情

<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. 执行部署流程

完成上述配置后，可以执行部署命令：

1. 清理并部署:

   mvn clean deploy

   登录后复制

   执行此命令时，Maven会：

   • 清理项目。
   • 编译、测试、打包主JAR。
   • 根据插件配置生成源码JAR (*-sources.jar)。
   • 根据插件配置生成Javadoc JAR (*-javadoc.jar)。
   • 使用GPG密钥对所有构件（包括POM文件）进行签名，并生成 .asc 签名文件。
   • 将所有生成的构件及其签名文件上传到 distributionManagement 中配置的仓库（对于发布版本是Sonatype的暂存仓库）。

2. 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的暂存仓库验证，将确保你的项目以完整的姿态呈现在全球开发者面前。

以上就是Maven项目部署至中央仓库：确保Javadoc和源码完整发布的指南的详细内容，更多请关注php中文网其它相关文章！