1. 项目概述与核心价值在上一篇文章里我们聊透了Maven组件化发布的前置准备包括多模块项目的结构设计、版本管理策略以及本地调试的“组合拳”。今天我们把目光聚焦到发布流程本身这是将我们精心打磨的组件推向“中央仓库”或“私有仓库”的关键一步。很多朋友在配置好pom.xml后执行mvn deploy命令要么遇到权限问题要么发现依赖传递不对要么就是快照版本和正式版本傻傻分不清楚最终导致发布失败或者发布后的组件无法被正常使用。这篇文章我将以一个资深“包工头”的视角带你深入Maven发布的“施工现场”。我们不止要搞清楚mvn clean deploy这条命令背后发生了什么更要掌握如何配置发布目标是发到Maven中央仓库还是公司内部的Nexus或Artifactory如何处理敏感信息如账号密码以及如何应对多模块项目发布时的依赖关系和构建顺序。我会分享我踩过的坑比如因为一个错误的distributionManagement配置导致整个团队半天无法获取最新依赖也会告诉你一些“偷懒”但高效的小技巧比如利用Maven的Profile和属性过滤实现一套配置适配多个环境。无论你是正在搭建公司内部组件库的架构师还是需要将自己开发的通用工具包共享出去的开发者这篇“中篇”都将为你提供一份可直接“抄作业”的实操指南。2. 发布目标配置深入理解distributionManagement发布组件首先得告诉Maven往哪儿发。这个“目的地”就是通过pom.xml中的distributionManagement元素来定义的。很多新手会把它和repositories依赖仓库搞混。简单来说repositories是“进货”的地方声明项目从哪里下载依赖而distributionManagement是“出货”的地方声明构建的产物JAR、源码、文档要上传到哪里。2.1 配置详解与双仓库策略一个完整的distributionManagement通常包含repository和snapshotRepository。为什么需要两个这体现了Maven对“快照版本”和“正式版本”的严格区分。distributionManagement !-- 正式版本Release发布仓库 -- repository idmy-company-releases/id nameCompany Release Repository/name urlhttps://nexus.mycompany.com/repository/maven-releases//url /repository !-- 快照版本Snapshot发布仓库 -- snapshotRepository idmy-company-snapshots/id nameCompany Snapshot Repository/name urlhttps://nexus.mycompany.com/repository/maven-snapshots//url /snapshotRepository /distributionManagement核心解析id这是仓库的唯一标识符必须与你在Maven配置文件settings.xml中配置的服务器serverid完全匹配。Maven在上传构件时会凭这个id去settings.xml里找对应的用户名和密码。大小写敏感一个字符都不能错。url仓库的访问地址。对于私有仓库如Nexus这通常是Web界面地址加上特定的仓库路径。注意releases仓库和snapshots仓库的URL路径通常是不同的这是仓库管理器的常规设置目的是将两类构件物理隔离。双仓库的必要性快照版本-SNAPSHOT代表不稳定、正在活跃开发的版本它允许重复发布每次deploy都会覆盖同版本号的时间戳构件。正式版本不带-SNAPSHOT则一旦发布便不可更改具有唯一性和稳定性。将两者分开发布到不同的仓库有利于依赖方清晰选择联调时依赖快照版本获取最新修复生产环境必须锁定某个正式版本。实操心得我强烈建议即使在开发阶段也尽量使用内部私服如Nexus的snapshots仓库而不是本地.m2仓库。这能让团队其他成员方便地共享和测试你的最新快照包避免“在我机器上是好的”这类问题。将distributionManagement配置在公司内部父POM或项目模板中是个一劳永逸的好习惯。2.2 认证信息的安全管理把用户名密码明文写在pom.xml里是绝对的大忌因为pom.xml通常会被提交到代码仓库。正确的做法是将认证信息配置在本地或持续集成CI服务器的~/.m2/settings.xml文件中。!-- ~/.m2/settings.xml -- settings servers server !-- 此id必须与pom.xml中distributionManagement的repository/id一致 -- idmy-company-releases/id usernamedeployment-user/username password{加密后的密码}/password /server server idmy-company-snapshots/id usernamedeployment-user/username password{加密后的密码}/password /server /servers /settings密码加密Maven支持对settings.xml中的密码进行简单加密。虽然这不是军用级加密但能避免密码以明文形式存储。可以使用mvn --encrypt-password命令生成加密串。对于CI环境更常见的做法是使用环境变量或CI工具提供的安全凭证管理功能在运行时动态注入。3. 多模块项目的发布流程与核心命令对于组件化项目我们通常有一个父POM和多个子模块。发布时我们需要确保所有模块按正确顺序构建并且最终只发布我们想要发布的模块比如通常不发布仅用于聚合的父POM模块本身。3.1 构建顺序与发布范围控制Maven会根据模块间的依赖关系自动计算构建顺序依赖者后于被依赖者构建。在根目录执行mvn deployMaven会递归地构建并发布所有子模块。但有时我们会有特殊需求仅发布某个子模块进入该子模块目录执行mvn deploy。跳过某个模块的发布在该模块的pom.xml中配置maven.deploy.skiptrue/maven.deploy.skip属性。不发布聚合父POM父POM的packaging类型通常是pom它本身不产生JAR等构件。默认情况下Maven也会为packaging为pom的模块生成一个pom.xml文件并部署到仓库这是必要的因为子模块依赖它来声明父POM信息。你不需要特别处理它。核心发布命令解析# 最常用清理、编译、测试、打包、安装到本地仓库、部署到远程仓库 mvn clean deploy # 跳过单元测试慎用仅在确定无需测试或调试时使用 mvn clean deploy -DskipTests # 同时跳过测试代码的编译 mvn clean deploy -Dmaven.test.skiptrue # 仅部署假设之前已经成功构建过 mvn deploymvn deploy阶段隐式包含了validate,compile,test,package,verify,install等所有前置阶段。它会将package阶段生成的构件JAR/WAR等以及由maven-javadoc-plugin和maven-source-plugin生成的源码包和文档包如果配置了的话一起上传到distributionManagement指定的仓库。3.2 源码与Javadoc附件的自动生成一个专业的组件发布除了主构件JAR还应该包含源代码-sources.jar和API文档-javadoc.jar。这极大方便了使用者在IDE中查看源码和文档。通过在父POM中配置插件可以一键为所有子模块启用此功能build plugins !-- 源码打包插件 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-source-plugin/artifactId version3.3.0/version executions execution idattach-sources/id goals goaljar-no-fork/goal /goals /execution /executions /plugin !-- Javadoc打包插件 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-javadoc-plugin/artifactId version3.6.0/version executions execution idattach-javadocs/id goals goaljar/goal /goals configuration !-- 可在此处配置Javadoc额外选项如编码、跳过错误等 -- charsetUTF-8/charset docencodingUTF-8/docencoding failOnErrorfalse/failOnError /configuration /execution /executions /plugin /plugins /build配置后执行mvn clean deploy这两个插件会在package阶段之后自动运行生成对应的-sources.jar和-javadoc.jar并随主构件一同被部署。踩坑记录maven-javadoc-plugin在遇到代码中的某些注释格式问题或依赖缺失时可能会导致构建失败。一个稳妥的做法是像上面配置一样先设置failOnErrorfalse/failOnError确保主构件能成功发布然后再逐步修复Javadoc问题。毕竟没有Javadoc的构件还能用但发布失败的构件谁也甭想用。4. 版本管理与发布生命周期发布不仅仅是执行一条命令更关乎版本号的规范管理。混乱的版本号是依赖地狱的开端。4.1 发布Release与快照Snapshot的严格纪律快照版本Snapshot版本号以-SNAPSHOT结尾例如1.0.0-SNAPSHOT。它代表“处于开发中的、不稳定的版本”。Maven对于快照版本的策略是“时常更新”。当你依赖一个快照版本时Maven在构建时可能会每天一次或每次构建都去远程仓库检查是否有更新的版本具体策略可配置。快照版本可以重复部署远程仓库会为其附加时间戳管理最新的构建。使用场景模块间并行开发、联调。A模块开发新功能需要B模块的最新改动B就可以发布快照版本供A依赖。正式版本Release版本号是干净的如1.0.0,1.2.1。它代表一个稳定的、不可变的发布单元。同一个正式版本号在Maven仓库中只能存在一份一旦发布内容就固定了。使用场景任何需要稳定性的环境如测试环境验收后、生产环境。发布流程中的版本转换一个标准的组件发布流程往往始于一个快照版本如1.1.0-SNAPSHOT。当功能开发完成准备发布时你需要将版本号中的-SNAPSHOT去掉变为1.1.0。执行mvn clean deploy将1.1.0正式版发布到releases仓库。将代码中的版本号更新为下一个开发周期版本例如1.2.0-SNAPSHOT或1.1.1-SNAPSHOT取决于你的版本策略。这个过程如果手动操作容易出错。因此社区有成熟的工具来自动化这个流程例如Maven Release Plugin。4.2 使用Maven Release Plugin进行自动化发布这个插件可以自动化执行上述“版本准备-发布-版本迭代”的完整生命周期。它主要包含两个目标mvn release:prepare检查本地是否有未提交的修改。检查项目是否有快照依赖通常正式发布时应避免。交互式询问用户输入要发布的版本号如1.1.0和新的开发版本号如1.2.0-SNAPSHOT。将POM中的所有版本号更新为发布版本并提交一个标签Tag到SCM如Git。将POM版本号更新为新的开发版本并提交。mvn release:perform基于上一步创建的标签签出代码。在这个“干净”的标签代码上执行mvn deploy将正式构件发布到仓库。基本配置示例plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-release-plugin/artifactId version3.0.0/version configuration tagNameFormatv{project.version}/tagNameFormat !-- 定义Git标签格式 -- autoVersionSubmodulestrue/autoVersionSubmodules !-- 为多模块项目自动更新子模块版本 -- releaseProfilesrelease/releaseProfiles !-- 发布时激活的Profile -- arguments-DskipTests/arguments !-- 传递给perform阶段mvn命令的参数 -- /configuration /plugin注意事项maven-release-plugin功能强大但略显“笨重”它与SCMGit/SVN紧密集成流程严格。在微服务架构和强调快速、频繁发布的今天许多团队转向了更灵活的“GitFlowCI/CD”模式在CI流水线中通过检测Git标签如v1.0.0自动触发构建和发布流程并利用versions-maven-plugin等工具来更新版本号。选择哪种方式取决于团队的协作规范和发布频率。5. 高级主题使用Profile实现环境隔离在实际企业中你可能需要将组件发布到不同的环境开发团队使用内部的Snapshots仓库对外提供的SDK则要发布到Maven中央仓库。硬编码多个distributionManagement显然不行。这时Maven的Profile就派上了大用场。Profile允许你定义一组配置只在特定条件下激活。我们可以为不同的发布目标创建不同的Profile。profiles !-- Profile 1: 发布到内部私服默认激活用于日常开发 -- profile idinternal/id activation activeByDefaulttrue/activeByDefault !-- 默认激活 -- /activation distributionManagement repository.../repository snapshotRepository.../snapshotRepository !-- 指向公司内部Nexus -- /distributionManagement /profile !-- Profile 2: 发布到Maven中央仓库通过Sonatype OSSRH -- profile idcentral/id distributionManagement repository idossrh/id urlhttps://s01.oss.sonatype.org/service/local/staging/deploy/maven2//url /repository snapshotRepository idossrh/id urlhttps://s01.oss.sonatype.org/content/repositories/snapshots/url /snapshotRepository /distributionManagement build plugins !-- 发布到中央仓库需要GPG签名和源码包 -- plugin... !-- gpg-maven-plugin -- /plugin plugin... !-- maven-source-plugin -- /plugin plugin... !-- maven-javadoc-plugin -- /plugin /plugins /build /profile /profiles使用方式日常开发发布快照mvn clean deploy使用默认的internalprofile。发布正式版到中央仓库mvn clean deploy -P central激活centralprofile。这样一套代码就能灵活适应不同的发布渠道。发布到Maven中央仓库Central Repository的流程更为复杂需要先在 OSSRH 申请项目配置正确的POM信息如SCM地址、许可证、开发者信息并使用gpg-maven-plugin对构件进行签名。这本身是一个大话题但核心思路正是通过Profile来管理这套特殊的配置。6. 常见问题排查与实战技巧即使配置看似完美发布过程也可能遇到各种问题。下面是一些典型场景和解决思路。6.1 认证失败401/403错误这是最常见的问题。错误信息通常包含“Return code is: 401”或“ReasonPhrase: Unauthorized”。排查步骤核对id确保pom.xml中distributionManagement/repository/id与settings.xml中server/id完全一致包括大小写。检查权限确认settings.xml中配置的用户名密码有目标仓库的部署Deploy权限。在Nexus中这通常由nx-deploy权限控制。验证网络与URL手动访问一下url看仓库地址是否正确网络是否通畅。有时仓库路径从/repository/maven-releases/变为了/repository/company-maven-releases/。密码加密问题如果使用了加密密码确认加密时使用的master password存放在settings-security.xml是正确的或者当前环境变量M2_HOME/MAVEN_HOME指向的Maven版本与加密时一致。6.2 构件已存在409错误尝试发布一个已经存在于releases仓库的相同版本构件时会收到“Return code is: 409”错误提示资源冲突。因为releases仓库是 immutable不可变的。解决方案发布新版本递增版本号。如果这是内部测试仓库且你确定要覆盖可以联系仓库管理员临时将该版本从仓库中删除或者配置Nexus的releases仓库策略为“允许重新部署”Allow Redeploy但这违背了正式版本不可变的原则不推荐在生产仓库使用。6.3 依赖解析失败构建成功但依赖方拉不到你的组件发布成功了但其他项目在依赖它时Maven报错找不到该构件。排查步骤检查仓库索引对于像Nexus这样的代理仓库/宿主仓库新发布的构件需要被索引后才能被搜索和解析。这个过程可能是异步的稍等几分钟再试。确认依赖坐标让依赖方检查其pom.xml中的groupId,artifactId,version是否与你发布的完全一致。检查仓库顺序依赖方的settings.xml或项目POM中配置的repositories是否包含了你的构件所在的仓库并且顺序靠前Maven按顺序查找。查看构件内容直接通过浏览器访问仓库URL查看构件是否完整上传通常应包含.pom,.jar,-sources.jar,-javadoc.jar等文件。6.4 多模块项目发布单个模块失败在根目录执行mvn deploy时某个子模块发布失败导致整个构建失败。处理策略定位问题仔细查看失败模块的构建日志通常是该模块自身的配置问题如错误的distributionManagement或网络问题。跳过失败模块临时如果急于发布其他模块可以使用-plproject list和-amalso make参数进行选择性构建。例如要构建并发布module-a及其依赖的所有模块但不包含出错的module-b可以在根目录执行mvn clean deploy -pl module-a -am但这需要你清楚模块间的依赖关系。根本解决修复失败模块的问题才是正道。7. 与CI/CD流水线集成在现代软件开发中手动执行mvn deploy已经过时。将发布流程集成到CI/CD如Jenkins、GitLab CI、GitHub Actions中是标准实践。核心思路触发条件通常向特定分支如main或master的合并或打上符合版本规范的Git标签如v1.0.0会触发发布流水线。环境配置在CI服务器的作业配置中安全地配置settings.xml包含仓库认证信息或者使用“密文”Secrets环境变量。执行命令流水线脚本中执行构建和发布命令。快照发布每次合并到开发分支后自动执行mvn clean deploy发布快照版本。正式发布当创建Git标签时触发一个专门的发布流水线。这个流水线会 a. 检出标签代码。 b. 执行mvn clean deploy通常还会运行集成测试。 c. 可选调用versions-maven-plugin将项目中的版本号自动升级为下一个快照版本并提交。一个简化的GitHub Actions工作流示例name: Publish to Maven Central on: push: tags: - v* # 当推送v开头的标签时触发 jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up JDK uses: actions/setup-javav3 with: java-version: 11 distribution: temurin - name: Publish to Central run: mvn clean deploy -P central --no-transfer-progress env: MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }} MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }} GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }} GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}通过CI/CD自动化发布过程变得可重复、可追溯、且安全将开发者从繁琐的命令行操作中解放出来专注于代码本身。
Maven组件发布实战：从distributionManagement配置到CI/CD集成
发布时间：2026/5/16 2:29:17
1. 项目概述与核心价值在上一篇文章里我们聊透了Maven组件化发布的前置准备包括多模块项目的结构设计、版本管理策略以及本地调试的“组合拳”。今天我们把目光聚焦到发布流程本身这是将我们精心打磨的组件推向“中央仓库”或“私有仓库”的关键一步。很多朋友在配置好pom.xml后执行mvn deploy命令要么遇到权限问题要么发现依赖传递不对要么就是快照版本和正式版本傻傻分不清楚最终导致发布失败或者发布后的组件无法被正常使用。这篇文章我将以一个资深“包工头”的视角带你深入Maven发布的“施工现场”。我们不止要搞清楚mvn clean deploy这条命令背后发生了什么更要掌握如何配置发布目标是发到Maven中央仓库还是公司内部的Nexus或Artifactory如何处理敏感信息如账号密码以及如何应对多模块项目发布时的依赖关系和构建顺序。我会分享我踩过的坑比如因为一个错误的distributionManagement配置导致整个团队半天无法获取最新依赖也会告诉你一些“偷懒”但高效的小技巧比如利用Maven的Profile和属性过滤实现一套配置适配多个环境。无论你是正在搭建公司内部组件库的架构师还是需要将自己开发的通用工具包共享出去的开发者这篇“中篇”都将为你提供一份可直接“抄作业”的实操指南。2. 发布目标配置深入理解distributionManagement发布组件首先得告诉Maven往哪儿发。这个“目的地”就是通过pom.xml中的distributionManagement元素来定义的。很多新手会把它和repositories依赖仓库搞混。简单来说repositories是“进货”的地方声明项目从哪里下载依赖而distributionManagement是“出货”的地方声明构建的产物JAR、源码、文档要上传到哪里。2.1 配置详解与双仓库策略一个完整的distributionManagement通常包含repository和snapshotRepository。为什么需要两个这体现了Maven对“快照版本”和“正式版本”的严格区分。distributionManagement !-- 正式版本Release发布仓库 -- repository idmy-company-releases/id nameCompany Release Repository/name urlhttps://nexus.mycompany.com/repository/maven-releases//url /repository !-- 快照版本Snapshot发布仓库 -- snapshotRepository idmy-company-snapshots/id nameCompany Snapshot Repository/name urlhttps://nexus.mycompany.com/repository/maven-snapshots//url /snapshotRepository /distributionManagement核心解析id这是仓库的唯一标识符必须与你在Maven配置文件settings.xml中配置的服务器serverid完全匹配。Maven在上传构件时会凭这个id去settings.xml里找对应的用户名和密码。大小写敏感一个字符都不能错。url仓库的访问地址。对于私有仓库如Nexus这通常是Web界面地址加上特定的仓库路径。注意releases仓库和snapshots仓库的URL路径通常是不同的这是仓库管理器的常规设置目的是将两类构件物理隔离。双仓库的必要性快照版本-SNAPSHOT代表不稳定、正在活跃开发的版本它允许重复发布每次deploy都会覆盖同版本号的时间戳构件。正式版本不带-SNAPSHOT则一旦发布便不可更改具有唯一性和稳定性。将两者分开发布到不同的仓库有利于依赖方清晰选择联调时依赖快照版本获取最新修复生产环境必须锁定某个正式版本。实操心得我强烈建议即使在开发阶段也尽量使用内部私服如Nexus的snapshots仓库而不是本地.m2仓库。这能让团队其他成员方便地共享和测试你的最新快照包避免“在我机器上是好的”这类问题。将distributionManagement配置在公司内部父POM或项目模板中是个一劳永逸的好习惯。2.2 认证信息的安全管理把用户名密码明文写在pom.xml里是绝对的大忌因为pom.xml通常会被提交到代码仓库。正确的做法是将认证信息配置在本地或持续集成CI服务器的~/.m2/settings.xml文件中。!-- ~/.m2/settings.xml -- settings servers server !-- 此id必须与pom.xml中distributionManagement的repository/id一致 -- idmy-company-releases/id usernamedeployment-user/username password{加密后的密码}/password /server server idmy-company-snapshots/id usernamedeployment-user/username password{加密后的密码}/password /server /servers /settings密码加密Maven支持对settings.xml中的密码进行简单加密。虽然这不是军用级加密但能避免密码以明文形式存储。可以使用mvn --encrypt-password命令生成加密串。对于CI环境更常见的做法是使用环境变量或CI工具提供的安全凭证管理功能在运行时动态注入。3. 多模块项目的发布流程与核心命令对于组件化项目我们通常有一个父POM和多个子模块。发布时我们需要确保所有模块按正确顺序构建并且最终只发布我们想要发布的模块比如通常不发布仅用于聚合的父POM模块本身。3.1 构建顺序与发布范围控制Maven会根据模块间的依赖关系自动计算构建顺序依赖者后于被依赖者构建。在根目录执行mvn deployMaven会递归地构建并发布所有子模块。但有时我们会有特殊需求仅发布某个子模块进入该子模块目录执行mvn deploy。跳过某个模块的发布在该模块的pom.xml中配置maven.deploy.skiptrue/maven.deploy.skip属性。不发布聚合父POM父POM的packaging类型通常是pom它本身不产生JAR等构件。默认情况下Maven也会为packaging为pom的模块生成一个pom.xml文件并部署到仓库这是必要的因为子模块依赖它来声明父POM信息。你不需要特别处理它。核心发布命令解析# 最常用清理、编译、测试、打包、安装到本地仓库、部署到远程仓库 mvn clean deploy # 跳过单元测试慎用仅在确定无需测试或调试时使用 mvn clean deploy -DskipTests # 同时跳过测试代码的编译 mvn clean deploy -Dmaven.test.skiptrue # 仅部署假设之前已经成功构建过 mvn deploymvn deploy阶段隐式包含了validate,compile,test,package,verify,install等所有前置阶段。它会将package阶段生成的构件JAR/WAR等以及由maven-javadoc-plugin和maven-source-plugin生成的源码包和文档包如果配置了的话一起上传到distributionManagement指定的仓库。3.2 源码与Javadoc附件的自动生成一个专业的组件发布除了主构件JAR还应该包含源代码-sources.jar和API文档-javadoc.jar。这极大方便了使用者在IDE中查看源码和文档。通过在父POM中配置插件可以一键为所有子模块启用此功能build plugins !-- 源码打包插件 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-source-plugin/artifactId version3.3.0/version executions execution idattach-sources/id goals goaljar-no-fork/goal /goals /execution /executions /plugin !-- Javadoc打包插件 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-javadoc-plugin/artifactId version3.6.0/version executions execution idattach-javadocs/id goals goaljar/goal /goals configuration !-- 可在此处配置Javadoc额外选项如编码、跳过错误等 -- charsetUTF-8/charset docencodingUTF-8/docencoding failOnErrorfalse/failOnError /configuration /execution /executions /plugin /plugins /build配置后执行mvn clean deploy这两个插件会在package阶段之后自动运行生成对应的-sources.jar和-javadoc.jar并随主构件一同被部署。踩坑记录maven-javadoc-plugin在遇到代码中的某些注释格式问题或依赖缺失时可能会导致构建失败。一个稳妥的做法是像上面配置一样先设置failOnErrorfalse/failOnError确保主构件能成功发布然后再逐步修复Javadoc问题。毕竟没有Javadoc的构件还能用但发布失败的构件谁也甭想用。4. 版本管理与发布生命周期发布不仅仅是执行一条命令更关乎版本号的规范管理。混乱的版本号是依赖地狱的开端。4.1 发布Release与快照Snapshot的严格纪律快照版本Snapshot版本号以-SNAPSHOT结尾例如1.0.0-SNAPSHOT。它代表“处于开发中的、不稳定的版本”。Maven对于快照版本的策略是“时常更新”。当你依赖一个快照版本时Maven在构建时可能会每天一次或每次构建都去远程仓库检查是否有更新的版本具体策略可配置。快照版本可以重复部署远程仓库会为其附加时间戳管理最新的构建。使用场景模块间并行开发、联调。A模块开发新功能需要B模块的最新改动B就可以发布快照版本供A依赖。正式版本Release版本号是干净的如1.0.0,1.2.1。它代表一个稳定的、不可变的发布单元。同一个正式版本号在Maven仓库中只能存在一份一旦发布内容就固定了。使用场景任何需要稳定性的环境如测试环境验收后、生产环境。发布流程中的版本转换一个标准的组件发布流程往往始于一个快照版本如1.1.0-SNAPSHOT。当功能开发完成准备发布时你需要将版本号中的-SNAPSHOT去掉变为1.1.0。执行mvn clean deploy将1.1.0正式版发布到releases仓库。将代码中的版本号更新为下一个开发周期版本例如1.2.0-SNAPSHOT或1.1.1-SNAPSHOT取决于你的版本策略。这个过程如果手动操作容易出错。因此社区有成熟的工具来自动化这个流程例如Maven Release Plugin。4.2 使用Maven Release Plugin进行自动化发布这个插件可以自动化执行上述“版本准备-发布-版本迭代”的完整生命周期。它主要包含两个目标mvn release:prepare检查本地是否有未提交的修改。检查项目是否有快照依赖通常正式发布时应避免。交互式询问用户输入要发布的版本号如1.1.0和新的开发版本号如1.2.0-SNAPSHOT。将POM中的所有版本号更新为发布版本并提交一个标签Tag到SCM如Git。将POM版本号更新为新的开发版本并提交。mvn release:perform基于上一步创建的标签签出代码。在这个“干净”的标签代码上执行mvn deploy将正式构件发布到仓库。基本配置示例plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-release-plugin/artifactId version3.0.0/version configuration tagNameFormatv{project.version}/tagNameFormat !-- 定义Git标签格式 -- autoVersionSubmodulestrue/autoVersionSubmodules !-- 为多模块项目自动更新子模块版本 -- releaseProfilesrelease/releaseProfiles !-- 发布时激活的Profile -- arguments-DskipTests/arguments !-- 传递给perform阶段mvn命令的参数 -- /configuration /plugin注意事项maven-release-plugin功能强大但略显“笨重”它与SCMGit/SVN紧密集成流程严格。在微服务架构和强调快速、频繁发布的今天许多团队转向了更灵活的“GitFlowCI/CD”模式在CI流水线中通过检测Git标签如v1.0.0自动触发构建和发布流程并利用versions-maven-plugin等工具来更新版本号。选择哪种方式取决于团队的协作规范和发布频率。5. 高级主题使用Profile实现环境隔离在实际企业中你可能需要将组件发布到不同的环境开发团队使用内部的Snapshots仓库对外提供的SDK则要发布到Maven中央仓库。硬编码多个distributionManagement显然不行。这时Maven的Profile就派上了大用场。Profile允许你定义一组配置只在特定条件下激活。我们可以为不同的发布目标创建不同的Profile。profiles !-- Profile 1: 发布到内部私服默认激活用于日常开发 -- profile idinternal/id activation activeByDefaulttrue/activeByDefault !-- 默认激活 -- /activation distributionManagement repository.../repository snapshotRepository.../snapshotRepository !-- 指向公司内部Nexus -- /distributionManagement /profile !-- Profile 2: 发布到Maven中央仓库通过Sonatype OSSRH -- profile idcentral/id distributionManagement repository idossrh/id urlhttps://s01.oss.sonatype.org/service/local/staging/deploy/maven2//url /repository snapshotRepository idossrh/id urlhttps://s01.oss.sonatype.org/content/repositories/snapshots/url /snapshotRepository /distributionManagement build plugins !-- 发布到中央仓库需要GPG签名和源码包 -- plugin... !-- gpg-maven-plugin -- /plugin plugin... !-- maven-source-plugin -- /plugin plugin... !-- maven-javadoc-plugin -- /plugin /plugins /build /profile /profiles使用方式日常开发发布快照mvn clean deploy使用默认的internalprofile。发布正式版到中央仓库mvn clean deploy -P central激活centralprofile。这样一套代码就能灵活适应不同的发布渠道。发布到Maven中央仓库Central Repository的流程更为复杂需要先在 OSSRH 申请项目配置正确的POM信息如SCM地址、许可证、开发者信息并使用gpg-maven-plugin对构件进行签名。这本身是一个大话题但核心思路正是通过Profile来管理这套特殊的配置。6. 常见问题排查与实战技巧即使配置看似完美发布过程也可能遇到各种问题。下面是一些典型场景和解决思路。6.1 认证失败401/403错误这是最常见的问题。错误信息通常包含“Return code is: 401”或“ReasonPhrase: Unauthorized”。排查步骤核对id确保pom.xml中distributionManagement/repository/id与settings.xml中server/id完全一致包括大小写。检查权限确认settings.xml中配置的用户名密码有目标仓库的部署Deploy权限。在Nexus中这通常由nx-deploy权限控制。验证网络与URL手动访问一下url看仓库地址是否正确网络是否通畅。有时仓库路径从/repository/maven-releases/变为了/repository/company-maven-releases/。密码加密问题如果使用了加密密码确认加密时使用的master password存放在settings-security.xml是正确的或者当前环境变量M2_HOME/MAVEN_HOME指向的Maven版本与加密时一致。6.2 构件已存在409错误尝试发布一个已经存在于releases仓库的相同版本构件时会收到“Return code is: 409”错误提示资源冲突。因为releases仓库是 immutable不可变的。解决方案发布新版本递增版本号。如果这是内部测试仓库且你确定要覆盖可以联系仓库管理员临时将该版本从仓库中删除或者配置Nexus的releases仓库策略为“允许重新部署”Allow Redeploy但这违背了正式版本不可变的原则不推荐在生产仓库使用。6.3 依赖解析失败构建成功但依赖方拉不到你的组件发布成功了但其他项目在依赖它时Maven报错找不到该构件。排查步骤检查仓库索引对于像Nexus这样的代理仓库/宿主仓库新发布的构件需要被索引后才能被搜索和解析。这个过程可能是异步的稍等几分钟再试。确认依赖坐标让依赖方检查其pom.xml中的groupId,artifactId,version是否与你发布的完全一致。检查仓库顺序依赖方的settings.xml或项目POM中配置的repositories是否包含了你的构件所在的仓库并且顺序靠前Maven按顺序查找。查看构件内容直接通过浏览器访问仓库URL查看构件是否完整上传通常应包含.pom,.jar,-sources.jar,-javadoc.jar等文件。6.4 多模块项目发布单个模块失败在根目录执行mvn deploy时某个子模块发布失败导致整个构建失败。处理策略定位问题仔细查看失败模块的构建日志通常是该模块自身的配置问题如错误的distributionManagement或网络问题。跳过失败模块临时如果急于发布其他模块可以使用-plproject list和-amalso make参数进行选择性构建。例如要构建并发布module-a及其依赖的所有模块但不包含出错的module-b可以在根目录执行mvn clean deploy -pl module-a -am但这需要你清楚模块间的依赖关系。根本解决修复失败模块的问题才是正道。7. 与CI/CD流水线集成在现代软件开发中手动执行mvn deploy已经过时。将发布流程集成到CI/CD如Jenkins、GitLab CI、GitHub Actions中是标准实践。核心思路触发条件通常向特定分支如main或master的合并或打上符合版本规范的Git标签如v1.0.0会触发发布流水线。环境配置在CI服务器的作业配置中安全地配置settings.xml包含仓库认证信息或者使用“密文”Secrets环境变量。执行命令流水线脚本中执行构建和发布命令。快照发布每次合并到开发分支后自动执行mvn clean deploy发布快照版本。正式发布当创建Git标签时触发一个专门的发布流水线。这个流水线会 a. 检出标签代码。 b. 执行mvn clean deploy通常还会运行集成测试。 c. 可选调用versions-maven-plugin将项目中的版本号自动升级为下一个快照版本并提交。一个简化的GitHub Actions工作流示例name: Publish to Maven Central on: push: tags: - v* # 当推送v开头的标签时触发 jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up JDK uses: actions/setup-javav3 with: java-version: 11 distribution: temurin - name: Publish to Central run: mvn clean deploy -P central --no-transfer-progress env: MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }} MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }} GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }} GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}通过CI/CD自动化发布过程变得可重复、可追溯、且安全将开发者从繁琐的命令行操作中解放出来专注于代码本身。
