在 Java 项目开发中，Maven 依赖问题很常见。
常见现象包括：
SNAPSHOT 版本不是最新的
依赖完全拉不下来
本地能构建，别人拉不下来
实际使用的依赖版本和预期不一致这些问题看起来都像是“依赖拉不下来”，但背后的原因可能完全不同。
有可能是：
本地缓存问题；
Nexus 私服没有对应包；
settings.xml配置错误；mirror拦截了请求；profile没有激活；多模块发布不完整；
父 POM 或 BOM 覆盖了版本；
SNAPSHOT metadata 没有刷新。
本文整理几个常见场景和排查方式。
一、问题速查表
遇到 Maven 依赖问题时，可以先按现象分类。
排查时不要直接猜。
先确认问题发生在哪一端：
Nexus 上没有：推送端问题
Nexus 上有，但本地拉不到：拉取端问题
版本不对：依赖解析或版本仲裁问题二、场景一：SNAPSHOT 版本不是最新的
1. 现象
你已经发布了：
1.0.0-SNAPSHOT但同事执行：mvn clean install 后，拉到的还是旧版本。
2. SNAPSHOT 的实际存储方式
SNAPSHOT 版本在 Maven 私服中并不是简单保存成一个固定文件。
例如：1.0.0-SNAPSHOT在 Nexus 中可能实际存储为：1.0.0-20231203.091530-1
Maven 会通过：maven-metadata.xml 判断当前最新的时间戳版本。
所以，SNAPSHOT 拉不到最新版本，通常和下面三个环节有关：
推送端：Nexus metadata 没更新
传输端：Maven updatePolicy 没触发检查
接收端：本地仓库缓存了旧版本三、排查 SNAPSHOT 是否最新
1. 查看 Nexus 上的 metadata
可以直接在 Nexus 页面查看，也可以用 curl 请求：
curl -s "http://your-nexus/repository/snapshots/com/yourcompany/your-artifact/1.0.0-SNAPSHOT/maven-metadata.xml"重点关注：
<lastUpdated>
<snapshotVersions>确认 metadata 中记录的时间戳是不是刚刚发布的版本。
如果 Nexus 上的 metadata 本身不是最新的，本地怎么强制更新也没有用。
2. 检查本地仓库缓存
本地 Maven 仓库一般在：
~/.m2/repository进入对应依赖目录：
ls -la ~/.m2/repository/com/yourcompany/your-artifact/1.0.0-SNAPSHOT/重点看几个文件：
jar 文件修改时间
_remote.repositories
resolver-status.properties
maven-metadata-*.xml其中：
_remote.repositories：记录当前依赖来自哪个仓库；resolver-status.properties：记录远程仓库检查状态；maven-metadata-*.xml：本地缓存的 metadata。
3. 强制更新 SNAPSHOT
可以使用：
mvn clean install -U-U 的作用是强制检查远程仓库的 SNAPSHOT 更新。
如果还不行，可以删除本地缓存后重新拉取：
rm -rf ~/.m2/repository/com/yourcompany/your-artifact/1.0.0-SNAPSHOT
mvn clean install四、检查 updatePolicy 配置
Maven 仓库可以配置 SNAPSHOT 的更新策略。
示例：
<repository>
<id>snapshots</id>
<url>http://your-nexus/repository/snapshots</url>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
</repository>updatePolicy 常见值：
如果配置成：
<updatePolicy>daily</updatePolicy>那么同一天内第二次构建可能不会再去检查远程仓库。
开发阶段如果频繁发布 SNAPSHOT，可以考虑使用：
<updatePolicy>always</updatePolicy>五、Nexus metadata 刷新问题
有时包已经上传，但 metadata 没有正确更新。
可以在 Nexus 管理界面中执行：
Administration -> Repository -> Repositories -> 选择仓库 -> Rebuild Index也可以通过 REST API 触发。
示例：
curl -X POST -u admin:password "http://your-nexus/service/rest/v1/repositories/snapshots/rebuild-index"不同 Nexus 版本接口可能不同，实际以当前 Nexus 版本为准。
六、场景二：依赖完全拉不下来
1. 现象
构建时报错类似：
Could not find artifact com.yourcompany:common-util:jar:1.0.0
in nexus (http://your-nexus/repository/public)这类问题要先确认：
私服上到底有没有这个 artifact。
2. 确认 Nexus 上是否存在
可以直接用浏览器访问，也可以用 curl：
curl -I "http://your-nexus/repository/releases/com/yourcompany/common-util/1.0.0/common-util-1.0.0.jar"
结果含义：
200：文件存在
404：文件不存在
401/403：认证或权限问题
如果 Nexus 上不存在，问题在发布端。
如果 Nexus 上存在，但 Maven 拉不到，问题在拉取端配置。
七、检查 settings.xml
1. mirror 拦截请求
常见配置：
<mirror>
<id>nexus</id>
<mirrorOf>*</mirrorOf>
<url>http://your-nexus/repository/public</url>
</mirror>这里的：
<mirrorOf>*</mirrorOf>表示所有仓库请求都会走这个 mirror。
如果你的依赖不在：
http://your-nexus/repository/public对应的仓库组中，就会一直拉不到。
所以要确认：
artifact 是否在仓库组里；
mirror 的地址是否正确；
mirror 是否误拦截了某些仓库。
2. repository 配置错误
检查 settings.xml 或 pom.xml 中的 repository：
<repository>
<id>releases</id>
<url>http://your-nexus/repository/releases</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>如果要拉 SNAPSHOT，需要确保：
<snapshots>
<enabled>true</enabled>
</snapshots>
如果要拉 release，需要确保：
<releases>
<enabled>true</enabled>
</releases>3. profile 没有激活
如果 repository 配置放在 profile 中，需要确认 profile 已激活。
查看当前激活的 profile：
mvn help:active-profiles查看最终生效的 settings：
mvn help:effective-settings如果 profile 没激活，对应仓库配置就不会生效。
八、开启 Debug 日志看 Maven 实际请求地址
有时候配置看起来没问题，但 Maven 实际请求的地址不是你以为的地址。
可以开启 debug 日志：
mvn clean install -X也可以过滤下载信息：
mvn clean install -X 2>&1 | grep -A5 "Downloading from"重点看：
Maven 实际请求哪个仓库
是否被 mirror 重定向
请求的是 releases 还是 snapshots
最终返回的是 404、401 还是 403九、多模块发布不完整
二方库发布时，多模块发布不完整是一个很常见的问题。
例如项目结构：
parent-pom
├── common-util
├── common-core
└── common-web你只发布了 common-util，但没有发布：
parent-pom
common-core
BOM别人拉取时就可能失败。
常见情况包括：
父 POM 没推；
子模块没推完整；
BOM 没推；
模块版本不一致；
某个传递依赖只存在本地。
检查父 POM 是否存在：
curl -I "http://your-nexus/repository/releases/com/yourcompany/parent-pom/1.0.0/parent-pom-1.0.0.pom"检查子模块 metadata：
for module in common-util common-core common-web; do
echo "Checking $module..."
curl -s "http://your-nexus/repository/releases/com/yourcompany/$module/maven-metadata.xml" | grep "<latest>"
done发布多模块项目时，最好由 CI 统一执行完整发布，避免人为漏发。
十、场景三：版本解析结果和预期不一致
1. 现象
你在 pom.xml 中写的是：
<version>1.2.0</version>但实际构建时使用的却是：
1.1.0这种问题通常不是“拉不下来”，而是 Maven 依赖版本解析结果和预期不一致。
2. 查看依赖树
查看指定依赖从哪里引入：
mvn dependency:tree -Dincludes=com.yourcompany:common-util如果想看冲突处理过程，可以用：
mvn dependency:tree -Dverbose它会显示重复依赖、冲突依赖以及最终被 Maven 选择的版本。
3. 查看 effective-pom
查看最终生效的 POM：
mvn help:effective-pom过滤指定依赖：
mvn help:effective-pom | grep -A10 "common-util"effective-pom 会把父 POM、BOM、profile、dependencyManagement 等合并后的最终配置展示出来。
如果实际版本不对，通常能在这里找到来源。
十一、Maven 版本仲裁规则
当同一个依赖被多条路径引入，并且版本不同时，Maven 会进行版本仲裁。
主要规则有三个。
1. 最短路径优先
例如：
A -> B -> C -> X:1.0
A -> D -> X:2.0X:2.0 路径更短，所以胜出。
2. 路径相同时，先声明优先
例如：
A -> B -> X:1.0
A -> C -> X:2.0如果 B 在 pom.xml 中声明在 C 前面，那么 X:1.0 胜出。
3. dependencyManagement 优先
如果在 dependencyManagement 中锁定了版本，Maven 会使用被管理的版本。
例如：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.yourcompany</groupId>
<artifactId>common-util</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</dependencyManagement>即使传递依赖中带来了其他版本，也可能最终被锁定为 1.0.0。
十二、常见版本冲突坑点
1. 父 POM 覆盖版本
子项目中写了：
<dependency>
<groupId>com.yourcompany</groupId>
<artifactId>common-util</artifactId>
<version>2.0.0</version>
</dependency>但父 POM 的 dependencyManagement 中写了：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.yourcompany</groupId>
<artifactId>common-util</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</dependencyManagement>
最终可能仍然使用 1.0.0。
排查方式：
mvn help:effective-pom2. BOM 覆盖版本
如果引入了 BOM：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.yourcompany</groupId>
<artifactId>your-bom</artifactId>
<version>1.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
BOM 中定义的版本会参与版本管理。
多个 BOM 同时存在时，还需要注意声明顺序和最终 effective-pom。
3. exclusion 排除了一个路径，但另一个路径又引入
例如你在 A 依赖上排除了 X：
<exclusions>
<exclusion>
<groupId>com.yourcompany</groupId>
<artifactId>x</artifactId>
</exclusion>
</exclusions>但 B 依赖又把 X 带进来了。
这时最终依赖树中仍然可能存在 X。
排查命令：
mvn dependency:tree -Dverbose十三、场景四：本地能跑，别人拉不下来
1. 现象
发布方说：
我本地构建没问题。使用方说：
我这里依赖拉不下来。这种情况很常见。
本地构建成功不代表私服上一定有这个依赖。
2. 可能原因
常见原因包括：
本地仓库有残留；
之前执行过
mvn install；deploy实际失败了；发布到了错误仓库；
父 POM 或子模块没有推完整；
settings.xml中 server 认证信息错误；distributionManagement指向了错误地址。
Maven 本地仓库会缓存依赖。
所以发布方本地能跑，可能只是因为：
~/.m2/repository 里已经有这个 jar但 Nexus 上并没有。
十四、发布后自检方式
发布完成后，建议发布方自己先做一次验证。
1. 清空本地缓存
rm -rf ~/.m2/repository/com/yourcompany/your-artifact/1.0.0-SNAPSHOT2. 重新从私服拉取
mvn dependency:get -Dartifact=com.yourcompany:your-artifact:1.0.0-SNAPSHOT3. 直接 curl 验证
curl -I "http://your-nexus/repository/snapshots/com/yourcompany/your-artifact/1.0.0-SNAPSHOT/your-artifact-1.0.0-SNAPSHOT.jar"如果自己清空本地缓存后都拉不下来，就说明没有发布成功，或者发布到了错误仓库。
十五、完整排查 Checklist
遇到依赖问题，可以按这个顺序排查。
1. 先定位问题在哪一端
先确认 Nexus 上有没有 artifact。
Nexus 没有：推送端问题
Nexus 有：拉取端问题
版本不对：版本仲裁问题可以使用：
curl -I "http://your-nexus/..."2. 推送端检查
检查这些问题：
deploy 命令是否成功
distributionManagement 地址是否正确
settings.xml 中 server 认证是否正确
是否推到了正确仓库
父 POM 是否发布
BOM 是否发布
所有子模块是否发布
模块版本是否一致3. 拉取端检查
检查这些问题：
settings.xml 中 repository 是否正确
mirror 是否拦截请求
profile 是否激活
releases / snapshots 是否启用
updatePolicy 是否符合预期
本地缓存是否已清理常用命令：
mvn help:effective-settings
mvn help:active-profiles
mvn clean install -U
4. 版本冲突检查
检查这些问题：
父 POM 是否锁版本
BOM 是否锁版本
传递依赖是否带来旧版本
exclusion 是否没有完全排除
dependencyManagement 是否覆盖常用命令：
mvn dependency:tree -Dincludes=groupId:artifactId
mvn dependency:tree -Dverbose
mvn help:effective-pom十六、常用命令速查
1. 强制更新 SNAPSHOT
mvn clean install -U2. 查看依赖树
mvn dependency:tree过滤指定依赖：
mvn dependency:tree -Dincludes=groupId:artifactId显示冲突过程：
mvn dependency:tree -Dverbose3. 查看 effective-pom
mvn help:effective-pom4. 查看 effective-settings
mvn help:effective-settings5. 查看激活的 profile
mvn help:active-profiles6. 分析依赖
mvn dependency:analyze用于找出未使用依赖和未声明依赖。
7. 下载单个依赖
mvn dependency:get -Dartifact=groupId:artifactId:version例如：
mvn dependency:get -Dartifact=com.yourcompany:your-artifact:1.0.0-SNAPSHOT8. 删除本地特定依赖缓存
rm -rf ~/.m2/repository/com/yourcompany/artifact-name9. 开启 Maven Debug 日志
mvn clean install -X10. 查看 Maven 实际下载地址
mvn clean install -X 2>&1 | grep -A5 "Downloading from"十七、实践建议
1. 二方库发布交给 CI
不要每个人手动本地 deploy。
更稳妥的是：
代码合并后由 CI 统一发布
发布前执行构建校验
发布后自动验证 artifact 是否存在这样可以减少“我本地能跑”的问题。
2. 多模块项目要统一发布
多模块项目不要只发布一个子模块。
需要确认：
父 POM
BOM
所有被依赖子模块
当前模块都已经发布。
3. SNAPSHOT 用于开发，Release 用于稳定交付
SNAPSHOT 适合开发阶段快速迭代。
正式交付给其他团队或生产使用时，应发布稳定 Release 版本。
4. settings.xml 要统一管理
团队内最好统一维护 Maven settings.xml 模板。
尤其是：
mirror
repository
server
profile不要每个人各配一套。
否则同一个项目在不同人机器上表现可能不一致。
5. 出问题先看 effective-pom 和 dependency:tree
很多 Maven 问题最终都能通过这两个命令定位：
mvn help:effective-pom
mvn dependency:tree -Dverbose一个看最终配置，一个看依赖路径。
结论
Maven 依赖问题看起来杂乱，但大多数可以归为几类：
SNAPSHOT 没更新；
私服上没有对应 artifact；
本地 settings 或 mirror 配置错误；
多模块发布不完整；
父 POM、BOM 或传递依赖导致版本冲突；
本地仓库残留导致“我本地可以”的假象。
排查时不要先猜原因。
更有效的方式是：