先说结论如果你团队里还在靠“把 jar 包扔到共享盘”或者“改版本号再手动 scp”来管理构件这篇文章适合你花十分钟看完。我这次把整个流程走了一遍——从零在阿里云上建一个私有 Maven 仓库再用命令行把项目发布成 Release 版本涉及的关键配置、踩过的坑、以及为什么有些操作不能省都会写清楚。很多人以为建私有仓库是件很重的事要买服务器、装 Nexus、配 Nginx、做备份想想就劝退了。实际上用阿里云制品仓库这类托管服务十分钟就能把一个能用的私有 Maven 仓库跑起来日常开发最核心的价值就两点一是自己公司内部的通用模块、二方库有地方放二是 Release 版本能统一管理、不被随便覆盖。配合 Maven 命令行整个发布过程完全可以脚本化不再依赖 IDE 里点来点去。1. 整体思路拆解私有仓库到底解决了什么问题1.1 没有私有仓库时开发协作有多别扭先从一个最常见的场景说起。假设你维护一个内部工具包比如加密组件、日志埋点 SDK或者公司的公共实体类模块另外两个项目都要依赖它。没有私有仓库的时候你大概会这么干把 jar 包放在文件服务器或者企业网盘上同事自己下载、自己扔到本地仓库直接让同事把项目源码拷过去自己 install 到本地更原始一点的直接把源码嵌到对方项目里顺带把依赖关系也复制一份这几种方式用一段时间就会出问题。最典型的是版本混乱你改了代码打的包还是1.0.0同事本地已经装了同一个坐标的 jarMaven 永远解析到旧的改了半天发现“改了个寂寞”。而且一旦依赖链拉长A 依赖 BB 依赖 C靠人工传文件的方式根本无法维护。私有 Maven 仓库就是专门解决这个问题的它有一个统一的坐标寻址规则groupId:artifactId:version三要素定位唯一构件它有版本管理能力SNAPSHOT 版本随便传、随便覆盖Release 版本默认不能覆盖防止线上依赖被偷偷改掉它还能做访问控制公司内部构件不会暴露到公网。1.2 为什么选阿里云托管仓库而不是自己搭 Nexus自己做 Nexus 的好处是“可控”但代价也明显你得腾出一台服务器装 Java 环境调 JVM 参数做磁盘备份还要考虑私服暴露到外网时的安全策略。如果你们团队规模不大、运维人力也不充足这笔投入其实不划算。阿里云制品仓库这类托管服务的优势是“开箱即用”。不需要你自己维护服务端仓库地址、权限管理、构建配置都在网页上搞定命令行照样是标准 Maven 操作。尤其是和云原生生态配合的时候构建机器不用额外配 hosts、不用拷证书只要在settings.xml里配好认证信息就能拉依赖、发构件。有一说一托管仓库也不是没有限制。比如你完全依赖云厂商的 SLA如果对方服务异常你这边除了等基本没有别的办法再比如有些私有化部署要求严格的团队数据不能出内网那就只能老老实实用 Nexus。但如果你的场景是常规的互联网公司研发阿里云私有 Maven 仓库作为团队内部二方库的中转站性价比很高。1.3 版本发布这件事为什么要用命令行很多开发者在 IDEA 里直接点 Maven 面板的deploy确实能发布但这对“可重复、可追溯”这两个要求很不友好。命令行发布有几个实际好处可以写进 CI 脚本发版本不再依赖某台开发者的电脑参数可以固化比如-Dmaven.test.skiptrue、-DaltDeploymentRepository统一了大家的发布行为配合maven-release-plugin可以自动完成版本号切换、打 tag、发布避免人肉改版本号时出错这次我实际操作下来最核心的路径就是先在阿里云上建仓库然后配置好 Maven 的认证和分发地址最后用命令行把项目推到远程仓库。下面一步步说。2. 在阿里云上创建私有 Maven 仓库的完整实操2.1 准备工作开通服务、规划仓库类型登录阿里云控制台后搜索“云效制品仓库”进入制品仓库服务。第一次使用会让你开通服务这个流程按提示走就行。关键点在创建仓库之前先想清楚两件事。第一仓库的“权限属性”。制品仓库会区分“私有”和“公开”。公司内部代码必须建私有仓库匿名用户无读取权限。如果你建的是公开仓库任何人都能用你的仓库地址拉取构件这通常不是你想要的结果。第二区分 Release 和 Snapshot。阿里云制品仓库支持在同一个仓库实例下创建多个仓库我强烈建议至少建两个 Maven 仓库一个专门放 Release 版本一个专门放 Snapshot 版本分开的好处是版本生命周期清晰。Release 仓库默认限制覆盖Snapshot 仓库允许覆盖这与 Maven 的“快照”语义完全一致后面发布的时候会用到。我这次实际创建了这样两个仓库仓库类型Maven权限私有普通仓库名例如example-release快照仓库名例如example-snapshot提示阿里云上的仓库地址长这样https://packages.aliyun.com/你的命名空间/maven/repository/仓库名/。命名空间在制品仓库页面右上角能看到后面配置pom.xml时会用到。2.2 创建仓库时的关键选项创建 Maven 仓库时页面上会让你填仓库名称。有一点容易忽略仓库类型选 “Maven”这会影响后续拉取依赖时的代理行为和构件的存储结构。仓库创建好之后进入仓库详情页你会看到几个重要信息仓库地址就是前面那个https://packages.aliyun.com/xxx/maven/repository/example-release/公共代理地址这个通常用来解决“公司内网不能访问中央仓库”的问题使用指南里面有配置settings.xml的模板片段如果你所在团队的机器网络访问 Maven Central 不稳定可以在仓库设置里把中央仓库代理加上。阿里云制品仓库支持配置代理源构建机拉依赖时直接走阿里云的内网加速地址比裸连中央仓库快不少。2.3 获取认证凭证用户名和密码这一步算是全流程里最容易被卡住的地方。阿里云制品仓库的认证信息跟你的云账号登录密码不是一回事需要单独设置。在仓库的“使用指南”里会引导你去配置个人访问令牌或者固定账号密码。操作路径大概是右上角个人设置 - 制品仓库密码或者直接用访问令牌。这个凭证专门用于 Maven 客户端访问制品仓库。注意保管好别往公共代码库里塞。我踩过的一个坑第一次发布时报 401我以为自己的云账号密码对其实要的是制品仓库的独立密码。这点在配置settings.xml时特别容易搞混。3. Maven 侧的配置细节settings.xml 与 pom.xml3.1 settings.xml 里配置 server 认证Maven 不会主动把密码写在pom.xml里因为pom.xml通常会提交进 Git所有人都能看见。正确做法是把访问仓库的凭据放到全局的settings.xml中通过server标签和id关联到具体的仓库地址。settings.xml一般位于WindowsC:\Users\你的用户名\.m2\settings.xmlmacOS / Linux~/.m2/settings.xml没有这个文件就新建一个。核心配置片段如下settings servers server idexample-release/id username你的制品仓库用户名/username password你的制品仓库密码或令牌/password /server server idexample-snapshot/id username你的制品仓库用户名/username password你的制品仓库密码或令牌/password /server /servers /settings这里有两个关键点。第一id必须唯一并且后面pom.xml里distributionManagement中的id要完全一致。id是 Maven 匹配认证信息的钥匙不一致就会 401。第二同一个账号可以同时访问你名下的多个仓库所以两个 server 的用户名密码可以一样但 id 不能一样。有些文档会告诉你把所有仓库共用一个 id实际会出问题因为 Maven 分发时是根据 id 找凭据的多个仓库 url 的 id 相同会导致认证串用。3.2 pom.xml 里配置 distributionManagement项目的pom.xml中你需要在project节点下增加distributionManagement告诉 Maven 当执行mvn deploy时把构件推到哪个远程仓库。典型的配置distributionManagement repository idexample-release/id urlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-release//url /repository snapshotRepository idexample-snapshot/id urlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-snapshot//url /snapshotRepository /distributionManagement注意id和settings.xml里的serverid一致url必须是制品仓库页面显示的完整地址不要漏掉结尾的斜杠更不能把网页控制台的地址填进来。从上面的配置能看出来Maven 判断一个项目是“快照版本”还是“发布版本”完全看版本号里有没有-SNAPSHOT后缀版本号1.0.0-SNAPSHOT- 部署到 snapshotRepository版本号1.0.0- 部署到 repository如果你只打算长期发布 Release 版本其实可以只在distributionManagement里配置一个repository省略快照仓库。但实际写代码过程中没有人只发正式版不写快照所以官方推荐把两个都配上。3.3 公共仓库加速与仓库组的概念阿里云制品仓库还有一个值得顺手配置的点公共代理。建好仓库后可以在仓库设置里添加公共仓库源比如 Maven Central、Google Maven 等。这样项目里的第三方依赖会优先通过阿里云的仓库拉取内网环境下往往快很多。本地settings.xml里设置mirror指向阿里云仓库的公共地址即可mirrors mirror idaliyun-public/id mirrorOf*/mirrorOf urlhttps://packages.aliyun.com/你的命名空间/maven/public/url /mirror /mirrors这样做会有一个隐患mirrorOf*会把中央仓库的请求全部路由到阿里云公共代理如果你同时配置了私有仓库的认证需要确认公共代理地址不需要认证或者配好对应 id。注意mirror和repository是不同的东西。mirror拦截的是依赖下载请求distributionManagement只管发布。两者不要混在一起配否则可能出现“依赖能拉但构件发不上去”的情况。4. 命令行发布 Release 版本两种姿势与实战记录4.1 先分清 Snapshot 和 Release 的语义命令行发布之前一定要理解 Maven 对这两个版本类型的处理逻辑。1.0.0-SNAPSHOT代表“开发中版本”Maven 每次构建都可能从远程仓库拉取最新快照所以允许反复覆盖1.0.0代表不可变版本一旦发布理论上不应该再改变内容。很多人发布时习惯把“上线”和“发版”混为一谈直接改版本号去掉-SNAPSHOT然后mvn deploy一次两次没问题但在发布同版本号时就会撞上私有仓库的覆盖保护。阿里云制品仓库默认对 Release 版本开启“不允许覆盖”这其实是刻意为之的安全机制。我建议团队里走一条相对标准的流程开发阶段版本号保持1.0.0-SNAPSHOT功能稳定后准备发1.0.0发布动作用 Maven 命令行完成保留执行日志如果发现发布错了修改代码后升到1.0.1而不是强行覆盖1.0.04.2 方式一直接用 mvn deploy 发布 Release最快的方式是手动把版本号改成不带-SNAPSHOT的正式版然后执行mvn clean deploy -Dmaven.test.skiptrue注意这里我建议使用-Dmaven.test.skiptrue而不是-DskipTests。区别在于-DskipTests只跳过测试执行但会先编译测试代码-Dmaven.test.skiptrue跳过测试代码的编译和执行发布二方库时更快发布第三方依赖到私有仓库时还要考虑pom.xml中是否生成了完整的打包产物。比如有些项目用了spring-boot-maven-plugin的repackage功能直接mvn deploy会把可执行 jar 传到仓库这通常不是我们想要的。如果你要发布的是被其他项目依赖的普通 jar需要在pom.xml里做好配置比如plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration classifierexec/classifier /configuration /plugin但这是另一个话题这里不展开。回到发布流程执行完mvn deploy后在阿里云制品仓库的网页上应该能立刻看到1.0.0目录。点进去确认里面生成的是 jar、pom、以及可能的 sources jar。如果只有 pom 没有 jar那通常是构建配置问题和仓库无关。4.3 方式二用 maven-release-plugin 走标准发布流程直接把版本号的-SNAPSHOT去掉再 deploy有一个现实问题这个动作不可追溯全靠开发者自觉。更规范一点的做法是用maven-release-plugin它把“版本号切换 - 构建 - 提交 tag - 发布 - 切回开发版本”这套流程自动化。不过这个插件用起来有个让人头疼的地方默认情况下它会做很多 SCM 检查。你的项目必须配置了scm信息并且 Git 工作区必须干净不能有未提交的改动。另外它默认是交互式执行会一路问你 release 版本号、tag 名称、下一个开发版本号如果是在脚本里跑得提前把参数都传进去。我在一个模拟项目 X 上执行的标准命令是这样的mvn release:clean release:prepare \ -DreleaseVersion1.0.0 \ -DdevelopmentVersion1.0.1-SNAPSHOT \ -Dtagproject-x-1.0.0 \ -Dmaven.test.skiptrue mvn release:perform这里面的参数含义releaseVersion发布版本号也就是这次要发布到私有仓库的版本developmentVersion发布完成后 pom 里自动切换回的下一个开发版本号tag在 Git 里打的 tag 名称推荐命名能一眼看出来是哪个项目哪个版本第一次执行release:prepare时插件会进行两项检查这两项检查也是新手最容易卡住的地方检查代码里是否还依赖了其他SNAPSHOT依赖。如果有插件会拒绝执行因为发布出来的 Release 版本不应该依赖不可变的东西。检查 Git 当前分支是否干净。插件要让 Maven 帮你自动改 pom 版本号并提交所以不能有未提交的手头改动。我在实际测试中故意留了一个未提交的文件结果插件直接报错Cannot release project with uncommitted changes遇到这个问题别慌git status看一下把需要提交的提交掉不需要的要么.gitignore掉要么临时移走。如果项目里确实有SNAPSHOT依赖无法立刻解决一个常用做法是给release:prepare加上参数-DignoreSnapshotstrue这个参数允许跳过 SNAPSHOT 依赖检查但你要自己想清楚发布的正式版里带着一个不稳定的快照依赖值得不值得。我个人只在内部工具发布时用这个参数对外发布的组件宁可不发也不带快照依赖。release:perform默认会读取release.properties这个文件是release:prepare阶段生成的。它从 tag 检出代码再执行deploy确保你发布的代码和 Git tag 里的内容完全一致。不过在阿里云私有仓库场景下直接用release:perform有一个需要留意的地方它执行 deploy 时使用的是当前pom.xml中的distributionManagement配置所以你在prepare阶段改好的发布版本会正确推到仓库。但如果你之前没有配好distributionManagementperform阶段会尝试推到 Maven Central 的地址然后报错。所以顺序一定是先配好 3.2 节的内容再来跑这个插件。4.4 发布第三方 jarmvn deploy:deploy-file还有一种常见需求你手头有一个第三方提供的 jar或者一个历史遗留下来的旧构件没有源码也没法构建但团队内部需要统一通过 Maven 依赖它。这种情况不需要写 pom 项目直接用一个命令就能上传mvn deploy:deploy-file \ -Dfile./sdk-2.1.0.jar \ -DgroupIdcom.example \ -DartifactIdsdk \ -Dversion2.1.0 \ -Dpackagingjar \ -DgeneratePomtrue \ -DrepositoryIdexample-release \ -Durlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-release/这里的repositoryId同样要和settings.xml里的 server id 对应。这个命令很适合放进内部的自动化脚本里把漏网 jar 批量补传到私有仓库。5. 常见问题与排查技巧实录5.1 401 Unauthorized认证信息不对现象mvn deploy时输出Failed to transfer file ... Return code is 401。排查步骤检查settings.xml里的serverid和pom.xml里repositoryid是否完全一致包括大小写检查用户名和密码是不是制品仓库专用的认证信息不是云账号登录密码如果用的是个人访问令牌确认令牌没过期且权限范围包含制品仓库这个问题的根源通常是 id 对不上Maven 压根没找到对应的凭据于是客户端就没带 Authorization 头服务端直接拒绝。5.2 403 Forbidden没有仓库权限现象认证通过了但服务器返回 403。这种一般是账号没有目标仓库的写入权限。阿里云制品仓库里仓库成员可以区分所有者、管理员、开发者、只读者。检查当前账号是否被添加到仓库的成员列表并且角色是“开发者”以上。还有一种特殊情况仓库设置为“公开读”但写权限仍然只对成员开放。如果你能拉取依赖但不能发布多半就是这个原因。5.3 400/405Release 版本不允许覆盖现象重复发布同一个1.0.0版本时服务器返回 400 或者 405提示构件已存在。这是阿里云制品仓库的 Release 防覆盖机制在起作用。对于正式版本默认任何账号都不能覆盖已存在的 jar。如果你确实因为发布失误想修正有两个选择在仓库设置里临时打开“允许覆盖 Release 版本”发布后立刻关掉。只建议管理员操作且要留下记录直接把版本号升到1.0.1发布一个新版本。这是更干净的做法从项目管理的角度看第二种明显更合理。线上已经有人下载了1.0.0并缓存到本地你强行覆盖仓库里的文件也无法保证所有开发者的本地仓库都更新。版本号升级是唯一可靠的方式。5.4 发布成功但网页上看不到有时候命令行提示BUILD SUCCESS但阿里云制品仓库的页面里刷新不出来此时不要怀疑人生通常是缓存问题。阿里云制品仓库的网页列表有短暂延迟尤其刚发布完马上刷新可能什么也没有。等几十秒再看。如果一直没有去“构建记录”或者“包的列表”里用groupId:artifactId搜索不要只看默认的目录列表。还有一个常见误解有人把url配成了仓库的“公共代理地址”比如/maven/public。这个地址是拉取公共依赖用的不是发布地址。发布地址必须是你自己创建的私有仓库的详情地址两者不是同一个东西。5.5 release:prepare 卡在交互式问答里mvn release:prepare默认是交互式的如果不加参数直接执行命令行会停在类似这样的提示上What is the release version for Project X? (com.example:x) 1.0.0: :在 CI 环境里这种交互式提问直接会导致任务挂起。解决办法就是在命令里把所有参数都传全mvn release:prepare -DreleaseVersion1.0.0 -DdevelopmentVersion1.0.1-SNAPSHOT -Dtagproject-x-1.0.0参数传全之后插件不会向你提任何问题日志一路走到底。如果你用的 Maven 版本比较新插件版本低于 3.0默认还会检查 SCM 提交确保发布失败时不会留下半截 tag。5.6 发布时自动带出源码 jar二方库通常需要附带源码包方便同事调试。可以在pom.xml里配置plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-source-plugin/artifactId version3.3.0/version executions execution idattach-sources/id goals goaljar-no-fallback/goal /goals /execution /executions /plugin这样执行mvn deploy时会打包出一个独立的 sources jar 并同步推送到私有仓库。IDE 里点“下载源码”时就能直接定位到代码不用再找同事要。不过要注意如果项目本身是 Spring Boot 应用并且用了 repackagemvn deploy默认会把可执行 jar 发上去而依赖方拉下来的是 fat jar里面是一层层嵌套的依赖容易出幺蛾子。这种情况下建议结合classifier设置或者干脆别用 Spring Boot 的repackage来构建二方库。6. 一点实际体会在阿里云上建私有 Maven 仓库本身没什么难度真正有价值的是把发布规范定下来。我自己的习惯是SNAPSHOT 版本随便玩Release 版本用命令行发布并且每次发布前都确认一下settings.xml和pom.xml里的 id 是对得上的。这个检查只需要十秒钟却能帮你省掉 401 和 403 的排查时间。最后再分享一个小技巧在项目的pom.xml里把distributionManagement写在靠前的位置并且加上注释说明每个仓库是干嘛的。听起来可能有点小题大做但团队里一旦有人接手你的项目看到清晰的发布地址配置就不会再去网上搜“Maven 私有仓库配置”也不会随手把 SNAPSHOT 发布到 Release 仓库里。干活的是 Maven省心的是规范。
先说结论如果你团队里还在靠“把 jar 包扔到共享盘”或者“改版本号再手动 scp”来管理构件这篇文章适合你花十分钟看完。我这次把整个流程走了一遍——从零在阿里云上建一个私有 Maven 仓库再用命令行把项目发布成 Release 版本涉及的关键配置、踩过的坑、以及为什么有些操作不能省都会写清楚。很多人以为建私有仓库是件很重的事要买服务器、装 Nexus、配 Nginx、做备份想想就劝退了。实际上用阿里云制品仓库这类托管服务十分钟就能把一个能用的私有 Maven 仓库跑起来日常开发最核心的价值就两点一是自己公司内部的通用模块、二方库有地方放二是 Release 版本能统一管理、不被随便覆盖。配合 Maven 命令行整个发布过程完全可以脚本化不再依赖 IDE 里点来点去。1. 整体思路拆解私有仓库到底解决了什么问题1.1 没有私有仓库时开发协作有多别扭先从一个最常见的场景说起。假设你维护一个内部工具包比如加密组件、日志埋点 SDK或者公司的公共实体类模块另外两个项目都要依赖它。没有私有仓库的时候你大概会这么干把 jar 包放在文件服务器或者企业网盘上同事自己下载、自己扔到本地仓库直接让同事把项目源码拷过去自己 install 到本地更原始一点的直接把源码嵌到对方项目里顺带把依赖关系也复制一份这几种方式用一段时间就会出问题。最典型的是版本混乱你改了代码打的包还是1.0.0同事本地已经装了同一个坐标的 jarMaven 永远解析到旧的改了半天发现“改了个寂寞”。而且一旦依赖链拉长A 依赖 BB 依赖 C靠人工传文件的方式根本无法维护。私有 Maven 仓库就是专门解决这个问题的它有一个统一的坐标寻址规则groupId:artifactId:version三要素定位唯一构件它有版本管理能力SNAPSHOT 版本随便传、随便覆盖Release 版本默认不能覆盖防止线上依赖被偷偷改掉它还能做访问控制公司内部构件不会暴露到公网。1.2 为什么选阿里云托管仓库而不是自己搭 Nexus自己做 Nexus 的好处是“可控”但代价也明显你得腾出一台服务器装 Java 环境调 JVM 参数做磁盘备份还要考虑私服暴露到外网时的安全策略。如果你们团队规模不大、运维人力也不充足这笔投入其实不划算。阿里云制品仓库这类托管服务的优势是“开箱即用”。不需要你自己维护服务端仓库地址、权限管理、构建配置都在网页上搞定命令行照样是标准 Maven 操作。尤其是和云原生生态配合的时候构建机器不用额外配 hosts、不用拷证书只要在settings.xml里配好认证信息就能拉依赖、发构件。有一说一托管仓库也不是没有限制。比如你完全依赖云厂商的 SLA如果对方服务异常你这边除了等基本没有别的办法再比如有些私有化部署要求严格的团队数据不能出内网那就只能老老实实用 Nexus。但如果你的场景是常规的互联网公司研发阿里云私有 Maven 仓库作为团队内部二方库的中转站性价比很高。1.3 版本发布这件事为什么要用命令行很多开发者在 IDEA 里直接点 Maven 面板的deploy确实能发布但这对“可重复、可追溯”这两个要求很不友好。命令行发布有几个实际好处可以写进 CI 脚本发版本不再依赖某台开发者的电脑参数可以固化比如-Dmaven.test.skiptrue、-DaltDeploymentRepository统一了大家的发布行为配合maven-release-plugin可以自动完成版本号切换、打 tag、发布避免人肉改版本号时出错这次我实际操作下来最核心的路径就是先在阿里云上建仓库然后配置好 Maven 的认证和分发地址最后用命令行把项目推到远程仓库。下面一步步说。2. 在阿里云上创建私有 Maven 仓库的完整实操2.1 准备工作开通服务、规划仓库类型登录阿里云控制台后搜索“云效制品仓库”进入制品仓库服务。第一次使用会让你开通服务这个流程按提示走就行。关键点在创建仓库之前先想清楚两件事。第一仓库的“权限属性”。制品仓库会区分“私有”和“公开”。公司内部代码必须建私有仓库匿名用户无读取权限。如果你建的是公开仓库任何人都能用你的仓库地址拉取构件这通常不是你想要的结果。第二区分 Release 和 Snapshot。阿里云制品仓库支持在同一个仓库实例下创建多个仓库我强烈建议至少建两个 Maven 仓库一个专门放 Release 版本一个专门放 Snapshot 版本分开的好处是版本生命周期清晰。Release 仓库默认限制覆盖Snapshot 仓库允许覆盖这与 Maven 的“快照”语义完全一致后面发布的时候会用到。我这次实际创建了这样两个仓库仓库类型Maven权限私有普通仓库名例如example-release快照仓库名例如example-snapshot提示阿里云上的仓库地址长这样https://packages.aliyun.com/你的命名空间/maven/repository/仓库名/。命名空间在制品仓库页面右上角能看到后面配置pom.xml时会用到。2.2 创建仓库时的关键选项创建 Maven 仓库时页面上会让你填仓库名称。有一点容易忽略仓库类型选 “Maven”这会影响后续拉取依赖时的代理行为和构件的存储结构。仓库创建好之后进入仓库详情页你会看到几个重要信息仓库地址就是前面那个https://packages.aliyun.com/xxx/maven/repository/example-release/公共代理地址这个通常用来解决“公司内网不能访问中央仓库”的问题使用指南里面有配置settings.xml的模板片段如果你所在团队的机器网络访问 Maven Central 不稳定可以在仓库设置里把中央仓库代理加上。阿里云制品仓库支持配置代理源构建机拉依赖时直接走阿里云的内网加速地址比裸连中央仓库快不少。2.3 获取认证凭证用户名和密码这一步算是全流程里最容易被卡住的地方。阿里云制品仓库的认证信息跟你的云账号登录密码不是一回事需要单独设置。在仓库的“使用指南”里会引导你去配置个人访问令牌或者固定账号密码。操作路径大概是右上角个人设置 - 制品仓库密码或者直接用访问令牌。这个凭证专门用于 Maven 客户端访问制品仓库。注意保管好别往公共代码库里塞。我踩过的一个坑第一次发布时报 401我以为自己的云账号密码对其实要的是制品仓库的独立密码。这点在配置settings.xml时特别容易搞混。3. Maven 侧的配置细节settings.xml 与 pom.xml3.1 settings.xml 里配置 server 认证Maven 不会主动把密码写在pom.xml里因为pom.xml通常会提交进 Git所有人都能看见。正确做法是把访问仓库的凭据放到全局的settings.xml中通过server标签和id关联到具体的仓库地址。settings.xml一般位于WindowsC:\Users\你的用户名\.m2\settings.xmlmacOS / Linux~/.m2/settings.xml没有这个文件就新建一个。核心配置片段如下settings servers server idexample-release/id username你的制品仓库用户名/username password你的制品仓库密码或令牌/password /server server idexample-snapshot/id username你的制品仓库用户名/username password你的制品仓库密码或令牌/password /server /servers /settings这里有两个关键点。第一id必须唯一并且后面pom.xml里distributionManagement中的id要完全一致。id是 Maven 匹配认证信息的钥匙不一致就会 401。第二同一个账号可以同时访问你名下的多个仓库所以两个 server 的用户名密码可以一样但 id 不能一样。有些文档会告诉你把所有仓库共用一个 id实际会出问题因为 Maven 分发时是根据 id 找凭据的多个仓库 url 的 id 相同会导致认证串用。3.2 pom.xml 里配置 distributionManagement项目的pom.xml中你需要在project节点下增加distributionManagement告诉 Maven 当执行mvn deploy时把构件推到哪个远程仓库。典型的配置distributionManagement repository idexample-release/id urlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-release//url /repository snapshotRepository idexample-snapshot/id urlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-snapshot//url /snapshotRepository /distributionManagement注意id和settings.xml里的serverid一致url必须是制品仓库页面显示的完整地址不要漏掉结尾的斜杠更不能把网页控制台的地址填进来。从上面的配置能看出来Maven 判断一个项目是“快照版本”还是“发布版本”完全看版本号里有没有-SNAPSHOT后缀版本号1.0.0-SNAPSHOT- 部署到 snapshotRepository版本号1.0.0- 部署到 repository如果你只打算长期发布 Release 版本其实可以只在distributionManagement里配置一个repository省略快照仓库。但实际写代码过程中没有人只发正式版不写快照所以官方推荐把两个都配上。3.3 公共仓库加速与仓库组的概念阿里云制品仓库还有一个值得顺手配置的点公共代理。建好仓库后可以在仓库设置里添加公共仓库源比如 Maven Central、Google Maven 等。这样项目里的第三方依赖会优先通过阿里云的仓库拉取内网环境下往往快很多。本地settings.xml里设置mirror指向阿里云仓库的公共地址即可mirrors mirror idaliyun-public/id mirrorOf*/mirrorOf urlhttps://packages.aliyun.com/你的命名空间/maven/public/url /mirror /mirrors这样做会有一个隐患mirrorOf*会把中央仓库的请求全部路由到阿里云公共代理如果你同时配置了私有仓库的认证需要确认公共代理地址不需要认证或者配好对应 id。注意mirror和repository是不同的东西。mirror拦截的是依赖下载请求distributionManagement只管发布。两者不要混在一起配否则可能出现“依赖能拉但构件发不上去”的情况。4. 命令行发布 Release 版本两种姿势与实战记录4.1 先分清 Snapshot 和 Release 的语义命令行发布之前一定要理解 Maven 对这两个版本类型的处理逻辑。1.0.0-SNAPSHOT代表“开发中版本”Maven 每次构建都可能从远程仓库拉取最新快照所以允许反复覆盖1.0.0代表不可变版本一旦发布理论上不应该再改变内容。很多人发布时习惯把“上线”和“发版”混为一谈直接改版本号去掉-SNAPSHOT然后mvn deploy一次两次没问题但在发布同版本号时就会撞上私有仓库的覆盖保护。阿里云制品仓库默认对 Release 版本开启“不允许覆盖”这其实是刻意为之的安全机制。我建议团队里走一条相对标准的流程开发阶段版本号保持1.0.0-SNAPSHOT功能稳定后准备发1.0.0发布动作用 Maven 命令行完成保留执行日志如果发现发布错了修改代码后升到1.0.1而不是强行覆盖1.0.04.2 方式一直接用 mvn deploy 发布 Release最快的方式是手动把版本号改成不带-SNAPSHOT的正式版然后执行mvn clean deploy -Dmaven.test.skiptrue注意这里我建议使用-Dmaven.test.skiptrue而不是-DskipTests。区别在于-DskipTests只跳过测试执行但会先编译测试代码-Dmaven.test.skiptrue跳过测试代码的编译和执行发布二方库时更快发布第三方依赖到私有仓库时还要考虑pom.xml中是否生成了完整的打包产物。比如有些项目用了spring-boot-maven-plugin的repackage功能直接mvn deploy会把可执行 jar 传到仓库这通常不是我们想要的。如果你要发布的是被其他项目依赖的普通 jar需要在pom.xml里做好配置比如plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration classifierexec/classifier /configuration /plugin但这是另一个话题这里不展开。回到发布流程执行完mvn deploy后在阿里云制品仓库的网页上应该能立刻看到1.0.0目录。点进去确认里面生成的是 jar、pom、以及可能的 sources jar。如果只有 pom 没有 jar那通常是构建配置问题和仓库无关。4.3 方式二用 maven-release-plugin 走标准发布流程直接把版本号的-SNAPSHOT去掉再 deploy有一个现实问题这个动作不可追溯全靠开发者自觉。更规范一点的做法是用maven-release-plugin它把“版本号切换 - 构建 - 提交 tag - 发布 - 切回开发版本”这套流程自动化。不过这个插件用起来有个让人头疼的地方默认情况下它会做很多 SCM 检查。你的项目必须配置了scm信息并且 Git 工作区必须干净不能有未提交的改动。另外它默认是交互式执行会一路问你 release 版本号、tag 名称、下一个开发版本号如果是在脚本里跑得提前把参数都传进去。我在一个模拟项目 X 上执行的标准命令是这样的mvn release:clean release:prepare \ -DreleaseVersion1.0.0 \ -DdevelopmentVersion1.0.1-SNAPSHOT \ -Dtagproject-x-1.0.0 \ -Dmaven.test.skiptrue mvn release:perform这里面的参数含义releaseVersion发布版本号也就是这次要发布到私有仓库的版本developmentVersion发布完成后 pom 里自动切换回的下一个开发版本号tag在 Git 里打的 tag 名称推荐命名能一眼看出来是哪个项目哪个版本第一次执行release:prepare时插件会进行两项检查这两项检查也是新手最容易卡住的地方检查代码里是否还依赖了其他SNAPSHOT依赖。如果有插件会拒绝执行因为发布出来的 Release 版本不应该依赖不可变的东西。检查 Git 当前分支是否干净。插件要让 Maven 帮你自动改 pom 版本号并提交所以不能有未提交的手头改动。我在实际测试中故意留了一个未提交的文件结果插件直接报错Cannot release project with uncommitted changes遇到这个问题别慌git status看一下把需要提交的提交掉不需要的要么.gitignore掉要么临时移走。如果项目里确实有SNAPSHOT依赖无法立刻解决一个常用做法是给release:prepare加上参数-DignoreSnapshotstrue这个参数允许跳过 SNAPSHOT 依赖检查但你要自己想清楚发布的正式版里带着一个不稳定的快照依赖值得不值得。我个人只在内部工具发布时用这个参数对外发布的组件宁可不发也不带快照依赖。release:perform默认会读取release.properties这个文件是release:prepare阶段生成的。它从 tag 检出代码再执行deploy确保你发布的代码和 Git tag 里的内容完全一致。不过在阿里云私有仓库场景下直接用release:perform有一个需要留意的地方它执行 deploy 时使用的是当前pom.xml中的distributionManagement配置所以你在prepare阶段改好的发布版本会正确推到仓库。但如果你之前没有配好distributionManagementperform阶段会尝试推到 Maven Central 的地址然后报错。所以顺序一定是先配好 3.2 节的内容再来跑这个插件。4.4 发布第三方 jarmvn deploy:deploy-file还有一种常见需求你手头有一个第三方提供的 jar或者一个历史遗留下来的旧构件没有源码也没法构建但团队内部需要统一通过 Maven 依赖它。这种情况不需要写 pom 项目直接用一个命令就能上传mvn deploy:deploy-file \ -Dfile./sdk-2.1.0.jar \ -DgroupIdcom.example \ -DartifactIdsdk \ -Dversion2.1.0 \ -Dpackagingjar \ -DgeneratePomtrue \ -DrepositoryIdexample-release \ -Durlhttps://packages.aliyun.com/你的命名空间/maven/repository/example-release/这里的repositoryId同样要和settings.xml里的 server id 对应。这个命令很适合放进内部的自动化脚本里把漏网 jar 批量补传到私有仓库。5. 常见问题与排查技巧实录5.1 401 Unauthorized认证信息不对现象mvn deploy时输出Failed to transfer file ... Return code is 401。排查步骤检查settings.xml里的serverid和pom.xml里repositoryid是否完全一致包括大小写检查用户名和密码是不是制品仓库专用的认证信息不是云账号登录密码如果用的是个人访问令牌确认令牌没过期且权限范围包含制品仓库这个问题的根源通常是 id 对不上Maven 压根没找到对应的凭据于是客户端就没带 Authorization 头服务端直接拒绝。5.2 403 Forbidden没有仓库权限现象认证通过了但服务器返回 403。这种一般是账号没有目标仓库的写入权限。阿里云制品仓库里仓库成员可以区分所有者、管理员、开发者、只读者。检查当前账号是否被添加到仓库的成员列表并且角色是“开发者”以上。还有一种特殊情况仓库设置为“公开读”但写权限仍然只对成员开放。如果你能拉取依赖但不能发布多半就是这个原因。5.3 400/405Release 版本不允许覆盖现象重复发布同一个1.0.0版本时服务器返回 400 或者 405提示构件已存在。这是阿里云制品仓库的 Release 防覆盖机制在起作用。对于正式版本默认任何账号都不能覆盖已存在的 jar。如果你确实因为发布失误想修正有两个选择在仓库设置里临时打开“允许覆盖 Release 版本”发布后立刻关掉。只建议管理员操作且要留下记录直接把版本号升到1.0.1发布一个新版本。这是更干净的做法从项目管理的角度看第二种明显更合理。线上已经有人下载了1.0.0并缓存到本地你强行覆盖仓库里的文件也无法保证所有开发者的本地仓库都更新。版本号升级是唯一可靠的方式。5.4 发布成功但网页上看不到有时候命令行提示BUILD SUCCESS但阿里云制品仓库的页面里刷新不出来此时不要怀疑人生通常是缓存问题。阿里云制品仓库的网页列表有短暂延迟尤其刚发布完马上刷新可能什么也没有。等几十秒再看。如果一直没有去“构建记录”或者“包的列表”里用groupId:artifactId搜索不要只看默认的目录列表。还有一个常见误解有人把url配成了仓库的“公共代理地址”比如/maven/public。这个地址是拉取公共依赖用的不是发布地址。发布地址必须是你自己创建的私有仓库的详情地址两者不是同一个东西。5.5 release:prepare 卡在交互式问答里mvn release:prepare默认是交互式的如果不加参数直接执行命令行会停在类似这样的提示上What is the release version for Project X? (com.example:x) 1.0.0: :在 CI 环境里这种交互式提问直接会导致任务挂起。解决办法就是在命令里把所有参数都传全mvn release:prepare -DreleaseVersion1.0.0 -DdevelopmentVersion1.0.1-SNAPSHOT -Dtagproject-x-1.0.0参数传全之后插件不会向你提任何问题日志一路走到底。如果你用的 Maven 版本比较新插件版本低于 3.0默认还会检查 SCM 提交确保发布失败时不会留下半截 tag。5.6 发布时自动带出源码 jar二方库通常需要附带源码包方便同事调试。可以在pom.xml里配置plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-source-plugin/artifactId version3.3.0/version executions execution idattach-sources/id goals goaljar-no-fallback/goal /goals /execution /executions /plugin这样执行mvn deploy时会打包出一个独立的 sources jar 并同步推送到私有仓库。IDE 里点“下载源码”时就能直接定位到代码不用再找同事要。不过要注意如果项目本身是 Spring Boot 应用并且用了 repackagemvn deploy默认会把可执行 jar 发上去而依赖方拉下来的是 fat jar里面是一层层嵌套的依赖容易出幺蛾子。这种情况下建议结合classifier设置或者干脆别用 Spring Boot 的repackage来构建二方库。6. 一点实际体会在阿里云上建私有 Maven 仓库本身没什么难度真正有价值的是把发布规范定下来。我自己的习惯是SNAPSHOT 版本随便玩Release 版本用命令行发布并且每次发布前都确认一下settings.xml和pom.xml里的 id 是对得上的。这个检查只需要十秒钟却能帮你省掉 401 和 403 的排查时间。最后再分享一个小技巧在项目的pom.xml里把distributionManagement写在靠前的位置并且加上注释说明每个仓库是干嘛的。听起来可能有点小题大做但团队里一旦有人接手你的项目看到清晰的发布地址配置就不会再去网上搜“Maven 私有仓库配置”也不会随手把 SNAPSHOT 发布到 Release 仓库里。干活的是 Maven省心的是规范。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
