Maven 中 -U 参数是否会强制更新所有依赖？dependency:purge-local-repository 如何重新下载 RELEASE 版本依赖

一、背景

在企业项目开发过程中，我们经常会遇到 Maven 依赖更新不生效的问题。

例如：

• 公司内部公共组件 common
• 业务基础包 model
• SNAPSHOT 版本频繁发布
• RELEASE 版本被重新部署覆盖

执行：

mvn clean package

发现：

• SNAPSHOT 依赖没有更新
• RELEASE 依赖仍然使用本地缓存版本

于是很多开发人员会想到：

mvn -U clean package

那么：

Maven 的 -U 参数到底会更新哪些依赖？

是否可以强制重新下载 RELEASE 版本？

本文详细说明。

---

二、Maven -U 参数作用

1. 什么是 -U？

Maven 命令：

-U

全称：

--update-snapshots

作用：

强制检查 SNAPSHOT 依赖是否存在更新。

例如：

项目依赖：

<dependency>
    <groupId>com.ha</groupId>
    <artifactId>common</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

本地 Maven 仓库：

~/.m2/repository/com/ha/common/1.0-SNAPSHOT

存在：

common-1.0-SNAPSHOT.jar

执行：

mvn -U clean package

Maven 会重新检查：

maven-metadata.xml

如果远程仓库存在新的 SNAPSHOT：

例如：

common-1.0-20260716.101010-5.jar

则重新下载。

---

三、-U 是否会更新 RELEASE 版本？

答案：

不会。

例如：

项目依赖：

<dependency>
    <groupId>com.ha</groupId>
    <artifactId>model</artifactId>
    <version>1.0.0</version>
</dependency>

本地：

~/.m2/repository/com/ha/model/1.0.0

存在：

model-1.0.0.jar

远程仓库：

model-1.0.0.jar

即使内容已经变化：

旧版本 jar
        ↓
重新 deploy
        ↓
新版本 jar

执行：

mvn -U clean package

Maven 仍然认为：

1.0.0 RELEASE版本已经存在

不会重新下载。

原因：

Maven 默认认为：

RELEASE 版本是不可变的。

也就是说：

1.0.0
1.0.1
2.0.0

这些版本发布后不应该修改。

---

四、Maven 本地仓库缓存机制

Maven 默认目录：

~/.m2/repository

例如：

.m2
 └── repository
      └── com
          └── ha
              └── common
                  └── 1.0.0
                      ├── common-1.0.0.jar
                      └── common-1.0.0.pom

Maven 判断：

依赖类型	默认行为
SNAPSHOT	允许检查更新
RELEASE	认为不可变
本地存在jar	优先使用

所以：

mvn -U

只能解决：

SNAPSHOT更新问题

不能解决：

RELEASE覆盖发布问题

---

五、dependency:purge-local-repository 强制清理依赖

如果希望重新下载 RELEASE 版本，可以使用：

mvn dependency:purge-local-repository

例如：

mvn dependency:purge-local-repository \
-DmanualInclude=com.ha:model,com.ha:common

作用：

删除：

~/.m2/repository/com/ha/model

~/.m2/repository/com/ha/common

然后 Maven 后续构建时重新下载。

---

六、推荐使用方式

方式一：清理指定依赖（推荐）

不要删除整个 Maven 仓库。

例如：

mvn dependency:purge-local-repository \
-DmanualInclude=com.ha:model,com.ha:common \
-DreResolve=false

然后：

mvn clean package \
-U \
-DskipTests=true \
-P prod

流程：

删除指定依赖
        |
        ↓
重新解析依赖
        |
        ↓
重新下载jar

---

七、一条命令完成清理并重新下载

可以：

mvn dependency:purge-local-repository \
-DmanualInclude=com.ha:model,com.ha:common \
-DreResolve=true \
-U \
clean package \
-DskipTests=true \
-Ddockerfile.skip=false \
-Pprod

其中：

-DmanualInclude

指定需要清理的依赖：

com.ha:model
com.ha:common

-DreResolve=true

表示：

清理后立即重新解析。

-U

继续检查 SNAPSHOT 更新。

---

八、企业 CI/CD 场景最佳实践

在 GitLab CI、Jenkins 中：

不建议每次执行：

dependency:purge-local-repository

原因：

会导致：

• 构建时间增加
• Maven 仓库频繁下载
• 私服压力增加

推荐策略：

---

1. SNAPSHOT 依赖

例如：

common-3.5-SNAPSHOT

使用：

mvn clean package -U

即可。

---

2. RELEASE 版本

例如：

common-3.5.0

正常情况下：

禁止覆盖发布。

推荐：

3.5.0
3.5.1
3.5.2

版本递增。

---

3. 如果私服允许覆盖 RELEASE

例如：

错误操作：

common-3.5.0.jar

重新 deploy。

那么：

清理：

rm -rf ~/.m2/repository/com/ha/common

然后：

mvn clean package

---

九、企业 Maven 仓库管理建议

Nexus / Artifactory 配置

建议：

RELEASE 仓库

禁止：

redeploy

例如：

禁止：

common-1.0.0.jar
        ↓
覆盖上传

应该：

common-1.0.0.jar

common-1.0.1.jar

SNAPSHOT 仓库

允许：

1.0-SNAPSHOT

持续发布。

---

十、总结

命令	作用	SNAPSHOT	RELEASE
mvn clean package	普通构建	❌不强制更新	❌不更新
mvn -U clean package	检查更新	✅更新	❌不更新
dependency:purge-local-repository	删除缓存	✅重新下载	✅重新下载
删除.m2目录	全部重新下载	✅	✅

实际项目推荐：

日常开发：
    mvn clean package -U

内部SNAPSHOT公共包：
    mvn clean package -U

怀疑RELEASE缓存问题：
    purge指定依赖

生产CI：
    禁止覆盖RELEASE版本

Maven 的设计理念是：

SNAPSHOT 可以变化，RELEASE 必须稳定。