Maven项目发布到中央仓库：确保Javadoc和源码正确上传的完整指南-java教程-PHP中文网

Maven项目发布到中央仓库：确保Javadoc和源码正确上传的完整指南

DDD

发布： 2025-10-02 10:08:31

原创

513人浏览过

Maven项目发布到中央仓库：确保Javadoc和源码正确上传的完整指南

本教程详细阐述了Maven项目发布到中央仓库时，如何解决Javadoc和源码丢失的问题。文章将指导读者配置Maven Source Plugin、Javadoc Plugin和GPG Plugin，确保在部署过程中正确生成并上传源码包和Javadoc包，同时涵盖GPG密钥生成、Sonatype OSSRH部署流程及注意事项，旨在帮助开发者顺利发布符合规范的开源库。

在将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 生成。打开终端并运行：

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

138

查看详情
```
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中央仓库进行访问了。