附录 1： Maven Central 发布完整指南：从零到成功部署

Java教程 • 2025-09-12

目录

  • 项目背景
  • 发布流程概览
  • 详细步骤
  • 遇到的坑和解决方案
  • 最佳实践
  • 总结

项目背景

项目：Simple Flow Framework

  • 一个轻量级、灵活的 Java 工作流引擎
  • 多模块 Maven 项目
  • 目标：发布到 Maven Central 供全球开发者使用

发布流程概览

graph TD
    A[准备阶段] --> B[Sonatype 账户设置]
    B --> C[GPG 密钥配置]
    C --> D[项目配置]
    D --> E[本地测试]
    E --> F[本地部署配置]
    F --> G[本地部署到 Maven Central]
    
    A --> A1[创建 Sonatype 账户]
    A --> A2[申请 GroupId]
    A --> A3[配置 GPG 密钥]
    
    D --> D1[更新 pom.xml]
    D --> D2[配置 settings.xml]
    D --> D3[设置环境变量]
    
    E --> E1[本地构建测试]
    E --> E2[GPG 签名测试]
    E --> E3[部署测试]
    
    F --> F1[设置环境变量]
    F --> F2[本地部署]
    F --> F3[验证发布]

详细步骤

1. Sonatype 账户设置

1.1 注册账户

  1. 访问 Sonatype Central

    • 打开 central.sonatype.com/publishing/…
    • 点击 "Sign in" 按钮

  2. 使用 GitHub 登录

    • 选择 "Sign in with GitHub"
    • 授权 Sonatype 访问你的 GitHub 账户
    • 完成 GitHub OAuth 认证

  3. 创建 Sonatype 账户

    • 填写个人信息（邮箱、姓名等）
    • 同意服务条款
    • 完成账户创建

1.2 申请 GroupId

  1. 创建 Namespace

    • 登录后点击 "Create Namespace"
    • 输入你想要的 GroupId（如：io.github.nemoob）
    • 选择命名空间类型（通常选择 "GitHub"）

  2. 验证 GitHub 仓库所有权

    • 系统会要求你验证 GitHub 仓库的所有权
    • 创建或选择一个 GitHub 仓库
    • 在仓库中创建一个文件来验证所有权

  3. 等待审核

    • 提交申请后等待审核
    • 通常需要 1-2 个工作日
    • 审核通过后会收到邮件通知

1.3 验证步骤

  1. 检查申请状态

    • 登录 central.sonatype.com/
    • 查看你的 Namespace 状态
    • 确认状态为 "Active"

  2. 验证 GitHub 仓库

    • 确保你的 GitHub 仓库是公开的
    • 确保仓库名称与申请的 GroupId 匹配
    • 例如：GroupId io.github.nemoob 对应仓库 nemoob/simpleflow

  3. 测试认证

    • 在 Sonatype Central 中查看你的账户信息
    • 确认你有发布权限
    • 检查 API Token 是否可用

1.4 获取认证信息

  1. 获取用户名和密码

    • 用户名：通常是你的 GitHub 用户名
    • 密码：使用 Sonatype 账户密码或 API Token

  2. 生成 API Token（推荐）

    • 在 Sonatype Central 中生成 API Token
    • 保存 Token 用于后续认证
    • 设置环境变量： 
      export OSSRH_USERNAME=your_github_username
export OSSRH_PASSWORD=your_api_token

  3. 验证认证信息

    • 测试登录 Sonatype Central
    • 确认可以访问你的 Namespace
    • 检查发布权限

2. GPG 密钥配置

2.1 生成 GPG 密钥

# 生成 GPG 密钥对
gpg --gen-key

# 查看公钥
gpg --armor --export your-email@example.com

# 查看私钥
gpg --armor --export-secret-key your-email@example.com

2.2 上传公钥到公钥服务器

# 上传公钥
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID

3. 项目配置

3.1 更新 pom.xml

"1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0modelVersion>

    <groupId>io.github.nemoobgroupId>
    <artifactId>simple-flow-parentartifactId>
    <version>1.0.0version>
    <packaging>pompackaging>

    <name>Simple Flow Frameworkname>
    <description>A lightweight, flexible workflow engine for Java applicationsdescription>
    <url>https://github.com/nemoob/simpleflowurl>

    
    <developers>
        <developer>
            <id>nemoobid>
            <name>nemoobname>
            <email>yang_zhong_ren@aliyun.comemail>
        developer>
    developers>

    
    <scm>
        <connection>scm:git:https://github.com/nemoob/simpleflow.gitconnection>
        <developerConnection>scm:git:ssh://github.com/nemoob/simpleflow.gitdeveloperConnection>
        <url>https://github.com/nemoob/simpleflowurl>
    scm>

    
    <licenses>
        <license>
            <name>Apache License, Version 2.0name>
            <url>http://www.apache.org/licenses/LICENSE-2.0.txturl>
            <distribution>repodistribution>
        license>
    licenses>

    
    <distributionManagement>
        <snapshotRepository>
            <id>ossrhid>
            <name>OSS Sonatype Snapshotsname>
            <url>https://central.sonatype.com/content/repositories/snapshotsurl>
        snapshotRepository>
        <repository>
            <id>ossrhid>
            <name>OSS Sonatype Releasesname>
            <url>https://central.sonatype.com/content/repositories/releasesurl>
        repository>
    distributionManagement>

    <build>
        
        <plugins>
            
            <plugin>
                <groupId>org.sonatype.centralgroupId>
                <artifactId>central-publishing-maven-pluginartifactId>
                <version>0.4.0version>
                <extensions>trueextensions>
                <configuration>
                    <publishingServerId>ossrhpublishingServerId>
                    <tokenAuth>truetokenAuth>
                configuration>
            plugin>

            
            <plugin>
                <groupId>org.apache.maven.pluginsgroupId>
                <artifactId>maven-source-pluginartifactId>
                <version>3.3.0version>
                <executions>
                    <execution>
                        <id>attach-sourcesid>
                        <phase>packagephase>
                        <goals>
                            <goal>jargoal>
                        goals>
                    execution>
                executions>
            plugin>

            
            <plugin>
                <artifactId>maven-javadoc-pluginartifactId>
                <version>3.3.0version>
                <configuration>
                    <additionalOptions>
                        
                        <additionalOption>-Xdoclint:noneadditionalOption>
                    additionalOptions>
                configuration>
                <executions>
                    <execution>
                        <id>attach-javadocsid>
                        <goals><goal>jargoal>goals>
                    execution>
                executions>
            plugin>

            
            <plugin>
                <groupId>org.apache.maven.pluginsgroupId>
                <artifactId>maven-gpg-pluginartifactId>
                <version>1.6version>
                <executions>
                    <execution>
                        <id>sign-artifactsid>
                        <phase>verifyphase>
                        <goals>
                            <goal>signgoal>
                        goals>
                    execution>
                executions>
            plugin>
        plugins>
    build>
project>

3.2 配置 settings.xml

"1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 
          http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>
    
    <server>
      <id>ossrhid>
      <username>${env.OSSRH_USERNAME}username>
      <password>${env.OSSRH_PASSWORD}password>
    server>
  servers>

  <profiles>
    <profile>
      <id>ossrhid>
      <activation>
        <activeByDefault>trueactiveByDefault>
      activation>
      <properties>
        <gpg.executable>gpggpg.executable>
        <gpg.passphrase>${env.GPG_PASSPHRASE}gpg.passphrase>
      properties>
    profile>
  profiles>

settings>

4. 本地部署配置

4.1 设置环境变量

在本地环境中设置以下环境变量：

# 设置 Sonatype 认证信息
export OSSRH_USERNAME=your_github_username
export OSSRH_PASSWORD=your_api_token_or_password

# 设置 GPG 密码
export GPG_PASSPHRASE=your_gpg_passphrase
export GPG_TTY=$(tty)

注意：

  • OSSRH_USERNAME: 通常是你的 GitHub 用户名
  • OSSRH_PASSWORD: 可以是 Sonatype 账户密码或 API Token（推荐使用 API Token）
  • GPG_PASSPHRASE: 你的 GPG 密钥密码

4.2 本地部署命令

# 构建并部署到 Maven Central
mvn clean install deploy -DskipTests -s settings.xml.template

4.3 验证结果

central.sonatype.com/publishing/… 看到需要验证，点击 Publish，大概等待 5-10 分钟即可。

最后在 central.sonatype.com/search?q=io… 搜索就可以看到结果了。

遇到的坑和解决方案

坑 1: 401 认证错误

错误信息：

Failed to deploy artifacts: Could not transfer artifact ... 401 Content access is protected by token

原因：

  • 使用了错误的 Sonatype URL
  • 认证信息不正确

解决方案：

  • 更新 URL 为新的 Sonatype Central 地址：https://central.sonatype.com/
  • 确保 GitHub Secrets 中的认证信息正确

坑 2: GPG 签名失败

错误信息：

Failed to execute goal org.apache.maven.plugins:maven-gpg-plugin:3.1.0:sign (sign-artifacts) on project simple-flow-parent: Exit code: 2

原因：

  • GPG 无法正确访问终端
  • 环境变量配置不正确

解决方案： 

# 设置 GPG 环境变量
export GPG_TTY=$(tty)
export GPG_AGENT_INFO=""

# 测试 GPG 签名
echo "test message" | gpg --clearsign

坑 3: 找不到 Artifact

错误信息：

Could not find artifact io.github.nemoob:simple-flow-api:jar:1.0.0-20250822.143840-1

原因：

  • 构建顺序不正确
  • 依赖的模块没有先构建

解决方案： 

# 按正确顺序构建所有模块
mvn clean install -DskipTests -s settings.xml.template

# 然后部署
mvn deploy -DskipTests -s settings.xml.template

坑 4: GroupId 不匹配

错误信息：

Could not find artifact io.github.nemoob:simple-flow-parent:pom:1.0.0-20250822.064503-1

原因：

  • 父 POM 和子模块的 GroupId 不一致
  • 依赖关系配置错误

解决方案：

  • 确保所有模块的 GroupId 都使用 io.github.nemoob
  • 检查所有子模块的 pom.xml 中的依赖配置

坑 5: Javadoc 生成失败

错误信息：

Could not find artifact io.github.nemoob:simple-flow-expression:jar:javadoc:1.0.0-20250822.135945-1

原因：

  • Javadoc 插件配置不正确
  • 某些模块缺少 Javadoc

解决方案： 

# 跳过 Javadoc 生成
mvn clean deploy -DskipTests -Dmaven.javadoc.skip=true -s settings.xml.template

# 或者修复 Javadoc 配置
mvn javadoc:jar -pl simple-flow-expression

坑 6: Maven Source 插件重复执行

错误信息：

Presumably you have configured maven-source-plugn to execute twice times in your build. You have to configure a classifier for at least on of them.

原因：

  • Maven Source 插件被配置了两次
  • 父 POM 和子模块都有配置

解决方案：

  • 移除重复的插件配置
  • 只在父 POM 中配置一次
  • 或者为其中一个配置 classifier

坑 7: 使用错误的发布插件

错误信息：

Could not find artifact ... Failed to deploy artifacts

原因：

  • 使用了旧的 Nexus Staging 插件
  • 没有使用 Sonatype Central 官方推荐的插件

解决方案： 


<plugin>
    <groupId>org.sonatype.centralgroupId>
    <artifactId>central-publishing-maven-pluginartifactId>
    <version>0.4.0version>
    <extensions>trueextensions>
    <configuration>
        <publishingServerId>ossrhpublishingServerId>
        <tokenAuth>truetokenAuth>
    configuration>
plugin>

最佳实践

1. 构建顺序很重要 

# 使用 install 而不是 package，确保依赖被安装到本地仓库
mvn clean install -DskipTests

2. 环境变量设置 

# 设置必要的环境变量
export GPG_TTY=$(tty)
export OSSRH_USERNAME=your_username
export OSSRH_PASSWORD=your_password
export GPG_PASSPHRASE=your_gpg_passphrase

3. 本地测试先行 

# 先在本地测试部署
mvn clean install deploy -DskipTests -s settings.xml.template

4. 版本管理

  • 使用语义化版本号
  • SNAPSHOT 版本用于测试
  • Release 版本用于正式发布

5. 文档和注释

  • 在 pom.xml 中添加详细的项目信息
  • 配置正确的 SCM 和开发者信息
  • 添加许可证信息

成功发布后的验证

1. 检查 Sonatype Central

  • 登录 central.sonatype.com/
  • 查看你的 Namespace 下是否有新的 artifact
  • 检查发布历史记录
  • 确认 artifact 状态为 "Published"

2. 检查 Maven Central

  • 访问 search.maven.org/
  • 搜索你的 GroupId 和 ArtifactId
  • 注意：SNAPSHOT 版本可能不会出现在搜索结果中
  • 正式版本（如 1.0.0）会在搜索结果中显示

3. 测试依赖引用


<dependency>
    <groupId>io.github.nemoobgroupId>
    <artifactId>simple-flow-apiartifactId>
    <version>1.0.0-SNAPSHOTversion>
dependency>


<dependency>
    <groupId>io.github.nemoobgroupId>
    <artifactId>simple-flow-apiartifactId>
    <version>1.0.0version>
dependency>

4. 验证发布成功

  1. 检查 artifact 文件

    • 确认 JAR 文件、源码 JAR、Javadoc JAR 都已上传
    • 检查 GPG 签名文件是否存在

  2. 测试下载

    # 测试从 Maven Central 下载
mvn dependency:get -Dartifact=io.github.nemoob:simple-flow-api:1.0.0

  3. 检查搜索索引

    • 等待 1-2 小时让搜索索引更新
    • 在 Maven Central 搜索中验证可见性

发布流程图

graph LR
    A[本地开发] --> B[配置 pom.xml]
    B --> C[配置 settings.xml]
    C --> D[设置 GitHub Secrets]
    D --> E[本地测试构建]
    E --> F[本地测试部署]
    F --> G[创建 GitHub Release]
    G --> H[触发 GitHub Actions]
    H --> I[构建和签名]
    I --> J[部署到 Sonatype Central]
    J --> K[同步到 Maven Central]
    K --> L[验证发布成功]
    
    E --> E1{构建成功?}
    E1 -->|否| E2[修复构建问题]
    E2 --> E
    
    F --> F1{部署成功?}
    F1 -->|否| F2[修复部署问题]
    F2 --> F
    
    I --> I1{签名成功?}
    I1 -->|否| I2[修复 GPG 问题]
    I2 --> I
    
    J --> J1{部署成功?}
    J1 -->|否| J2[修复认证问题]
    J2 --> J

总结

发布到 Maven Central 是一个需要耐心和细致的过程。主要注意点：

  1. 配置要完整 - pom.xml、settings.xml、环境变量都要正确配置
  2. 认证要正确 - Sonatype 账户、GPG 密钥都要正确设置
  3. 构建顺序要正确 - 多模块项目要按依赖顺序构建
  4. 测试要充分 - 先在本地测试，确保部署成功
  5. 文档要详细 - 项目信息、许可证、SCM 都要配置完整
  6. 使用正确的插件 - 使用 Sonatype Central 官方推荐的 central-publishing-maven-plugin
  7. 避免重复配置 - 确保插件配置不重复，避免冲突

成功案例

通过本文的指导，Simple Flow Framework 已经成功发布到 Maven Central！

  • 项目地址: github.com/nemoob/simp…
  • GroupId: io.github.nemoob
  • 版本: 1.0.0
  • 状态: 发布成功

通过本文的指导，你应该能够成功将项目发布到 Maven Central，让全球的开发者都能使用你的库！

相关文章

[Java] 浅析可重复注解(Repeatable Annotation) 是如何实现的

2025-09-11

最全100道JAVA八股文，终于整理完了

2025-09-11

0基础带你精通Java对象序列化--以Hessian为例｜得物技术

2025-09-11

Spring Bean线程安全陷阱：90%程序员都会踩的坑，你中招了吗？

2025-09-11

推荐阅读

Java HashMap 扩容机制详解：触发条件与实现原理

2025-09-11

Java 实现异步转同步的方法

2025-09-12

HashMap 扩容为啥总是 2 的倍数？一场来自底层的“强迫症”探险

2025-09-12

对决剑之川抽卡玩法详解

2025-09-11