maven上传至中央仓库

发表于 更新于 分类于 Waline： 阅读次数： 本文字数： 6.6k 阅读时长 ≈ 6 分钟

Maven 上传项目至中央仓库：从申请到发布的完整指南

将自己开发的工具包上传至 Maven 中央仓库，能让全球开发者通过简单的依赖坐标直接使用，是开源贡献的重要一步。本文基于 Sonatype OSSRH（Open Source Software Repository Hosting）平台，详细讲解从账号注册到最终发布的全流程。

准备工作

必要条件

  • 一个公开的代码仓库（如 GitHub、Gitee），用于托管项目源码。
  • 一个可验证的域名（如个人域名或代码平台域名，用于 GroupId 验证）。
  • 安装 GPG（用于对发布文件进行签名，确保完整性）。

环境配置

  • GPG 安装：

    • Windows：使用 Gpg4win。
    • Mac：使用 GPG Suite。
    • Linux：通过包管理器安装（如 sudo apt install gnupg）。

创建gpg

  • 生成 GPG 密钥：
    打开终端执行以下命令，按提示输入姓名、邮箱和密码：

    gpg --full-generate-key

    生成后，上传公钥至公共服务器（确保 Maven 能验证签名）：

    gpg --keyserver hkp://keyserver.ubuntu.com:80 --send-keys 你的密钥ID

    （密钥 ID 可通过 gpg --list-keys 查看，格式为 8 位十六进制数）

Sonatype 账号与项目申请

Maven 中央仓库通过 Sonatype OSSRH 管理开源项目，需先注册并申请项目托管。

注册 Sonatype 账号

访问 Sonatype JIRA 注册账号，填写用户名、邮箱等信息（建议使用常用邮箱，后续验证需要）。

注册地址：https://issues.sonatype.org/secure/Signup!default.jspa

注册页

创建项目发布申请（New Issue）

  1. 登录后点击 Create 按钮，选择：

    • Project：Community Support - Open Source Project Repository Hosting
    • Issue Type：New Project

  2. 填写申请信息：

    • Summary：项目名称（如 tools-java: 通用工具类库）。
    • Group Id：项目的 Maven GroupId（关键！需验证所有权）。
      • 若有个人域名（如 example.com），可设为 com.example。
      • 若无域名，使用代码托管平台域名（如 Gitee 项目 gitee.com/yourname/tools-java，则 GroupId 为 io.gitee.yourname）。
    • Project URL：项目源码地址（如 https://gitee.com/yourname/tools-java）。
    • SCM URL：源码仓库地址（如 https://gitee.com/yourname/tools-java.git）。
    • Other Details：简要描述项目功能。

    新建项目

提交完成之后，会创建一个Issues

issue详细

验证 GroupId 所有权

提交申请后，Sonatype 工作人员会在 1-2 个工作日内回复，要求验证 GroupId 所有权：

  • 若使用个人域名：在 DNS 解析中添加 TXT 记录，值为 JIRA issue 编号（如 OSSRH-12345）。

    验证方式一

  • 若使用代码平台域名：在代码仓库中创建一个与 JIRA issue 同名的公共仓库（如 https://gitee.com/yourname/OSSRH-12345）。

    验证方式二

完成验证后回复工作人员，待审核通过（状态变为 RESOLVED），即可开始发布。

项目配置（pom.xml）

需在 pom.xml 中添加必要的元数据和插件配置，满足中央仓库的规范。

基本信息配置

添加项目描述、开源协议、开发者信息等：

<project>
  <!-- 基本坐标（GroupId 需与申请一致） -->
  <groupId>io.gitee.yourname</groupId>
  <artifactId>tools-util</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <name>tools-util</name>
  <description>工作中常用的工具类库，包含加密、日期处理等功能</description>
  <url>https://gitee.com/yourname/tools-java</url>

  <!-- 开源协议（必填，如 BSD、MIT 等） -->
  <licenses>
    <license>
      <name>BSD 3-Clause License</name>
      <url>https://opensource.org/licenses/BSD-3-Clause</url>
    </license>
  </licenses>

  <!-- 源码仓库信息 -->
  <scm>
    <connection>scm:git:https://gitee.com/yourname/tools-java.git</connection>
    <developerConnection>scm:git:https://gitee.com/yourname/tools-java.git</developerConnection>
    <url>https://gitee.com/yourname/tools-java</url>
  </scm>

  <!-- 开发者信息 -->
  <developers>
    <developer>
      <name>yourname</name>
      <email>your-email@example.com</email>
      <roles>
        <role>Developer</role>
      </roles>
      <timezone>+8</timezone>
    </developer>
  </developers>
</project>

发布配置与插件

添加部署地址、签名插件、源码和文档插件：

<project>
  <!-- 部署地址（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>

  <build>
    <plugins>
      <!-- 1. 源码打包插件（必填，中央仓库要求提供源码） -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>3.2.1</version>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

      <!-- 2. Javadoc 插件（必填，提供 API 文档） -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.5.0</version>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
            <configuration>
              <doclint>none</doclint> <!-- 忽略注释不规范的错误 -->
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- 3. GPG 签名插件（必填，对发布文件签名）
 发布到Maven仓库中的所有文件都要使用GPG签名，以保障完整性。我们需要在本地安装并配置GPG。需要确认下命令行下的gpg是可用的 -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-gpg-plugin</artifactId>
        <version>1.5</version>
        <executions>
          <execution>
            <id>sign-artifacts</id>
            <phase>verify</phase>
            <goals>
              <goal>sign</goal>
            </goals>
            <configuration>
              <keyname>你的GPG密钥ID</keyname> <!-- 如 1234ABCD -->
              <passphraseServerId>gpg-passphrase</passphraseServerId> <!-- 与 settings.xml 中一致 -->
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- 4. Nexus 发布插件（简化 Staging 操作） -->
      <plugin>
        <groupId>org.sonatype.plugins</groupId>
        <artifactId>nexus-staging-maven-plugin</artifactId>
        <version>1.6.8</version>
        <extensions>true</extensions>
        <configuration>
          <serverId>ossrh</serverId>
          <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
          <!-- 设置为true后，close时会自动进行Release。我先设为false，自己体验了一把过程，顺便按照要求把验证过了。因为一开始 开源协议、SCM信息以及作者信息都没填 -->
          <autoReleaseAfterClose>false</autoReleaseAfterClose> <!-- 首次建议手动发布 -->
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

配置 Maven 全局设置（settings.xml）

在 settings.xml（通常位于 ~/.m2/settings.xml）中添加 Sonatype 账号和 GPG 密码：

<settings>
  <servers>
    <!-- Sonatype OSSRH 账号（用于部署） -->
    <server>
      <id>ossrh</id>
      <username>你的Sonatype用户名</username>
      <password>你的Sonatype密码</password>
    </server>

    <!-- GPG 签名密码（可选，避免每次输入） -->
    <server>
      <id>gpg-passphrase</id>
      <passphrase>你的GPG密钥密码</passphrase>
    </server>
  </servers>
</settings>

部署与发布流程

部署到 Staging 仓库

执行命令将项目部署到 Sonatype 的临时仓库（Staging）：

mvn clean deploy
  • 若版本号含 -SNAPSHOT（如 1.0.0-SNAPSHOT），会部署到 snapshots 仓库。
  • 若为正式版本（如 1.0.0），会部署到 Staging 仓库等待审核。

验证与发布（正式版本）

  1. 登录 Sonatype Nexus 控制台，使用 Sonatype 账号登录。
  2. 进入 Staging Repositories，找到刚部署的仓库（通常以 io-gitee-yourname 开头）。

上传之后，jar包会放到staging暂存库中，我们需要将其发布到release库

close

  1. Close仓库：点击Close按钮，系统会自动验证发布规则（如是否包含源码、签名是否有效）。

rule

  • 若验证失败，查看 Activity 标签的错误信息，修复后重新部署。
  1. Release 仓库：验证通过后，点击 Release 按钮，将项目发布到中央仓库。

Release

第一次发布成功后，在创建项目的issue上会有新的评论

sync

同步至 Maven 中央仓库

发布后，Sonatype 会自动同步到 Maven 中央仓库：

常见问题与解决

1. GPG 签名失败

  • 错误：gpg: signing failed: Inappropriate ioctl for device

  • 解决：在命令前添加GPG_TTY=$(tty)，确保终端支持交互：

    GPG_TTY=$(tty) mvn clean deploy

2. 验证规则失败

  • 错误：Failed to close staging repository ... due to failing rules
  • 解决：查看 Nexus 控制台的Activity日志，常见原因包括：
    • 缺少源码或 Javadoc Jar 包（确保插件配置正确）。
    • 未签名（检查 GPG 插件和密钥配置）。
    • 元数据不全（补充 licenses、scm、developers 配置）。

3. 版本重复发布

  • 注意：正式版本（非 SNAPSHOT）一旦发布无法修改或删除，若需更新需递增版本号（如 1.0.1）