Maven 依赖管理

掌握 Maven 依赖管理，包括依赖声明、作用域管理、版本解析、BOM（物料清单）以及依赖树优化。

概述

Maven 的依赖管理是 Java 项目构建系统的核心机制。它处理传递性依赖、版本冲突，并为多模块项目提供跨模块的依赖解析控制能力。

依赖声明

基础依赖

    org.springframework.boot
    spring-boot-starter-web
    3.2.0

带作用域的依赖

    org.junit.jupiter
    junit-jupiter
    5.10.1
    test

可选依赖

    com.google.code.findbugs
    jsr305
    3.0.2
    true

依赖作用域

可用作用域

作用域示例

    org.apache.commons
    commons-lang3
    3.14.0




    jakarta.servlet
    jakarta.servlet-api
    6.0.0
    provided




    org.postgresql
    postgresql
    42.7.1
    runtime




    org.mockito
    mockito-core
    5.8.0
    test

版本管理

基于属性的版本声明

    3.2.0
    5.10.1
    2.16.0



    
        org.springframework.boot
        spring-boot-starter-web
        ${spring-boot.version}
    

版本范围

1.0.0


[1.0.0,)


(,1.0.0)


[1.0.0,2.0.0]


(1.0.0,2.0.0)

最新版本（不推荐）

LATEST
RELEASE

依赖管理（dependencyManagement）节

集中化版本控制

    
        
            org.springframework.boot
            spring-boot-dependencies
            3.2.0
            pom
            import
        
        
            com.fasterxml.jackson
            jackson-bom
            2.16.0
            pom
            import
        
    




    
        org.springframework.boot
        spring-boot-starter-web
    
    
        com.fasterxml.jackson.core
        jackson-databind
    

BOM（物料清单）导入

    
        
        
            org.springframework.boot
            spring-boot-dependencies
            3.2.0
            pom
            import
        

        
        
            software.amazon.awssdk
            bom
            2.23.0
            pom
            import
        

        
        
            org.junit
            junit-bom
            5.10.1
            pom
            import
        
    

排除（Exclusions）

排除传递性依赖

    org.springframework.boot
    spring-boot-starter-web
    
        
            org.springframework.boot
            spring-boot-starter-tomcat
        
    




    org.springframework.boot
    spring-boot-starter-jetty

排除日志框架

    org.springframework.boot
    spring-boot-starter
    
        
            org.springframework.boot
            spring-boot-starter-logging
        
    



    org.springframework.boot
    spring-boot-starter-log4j2

依赖分析

查看依赖树

# 完整依赖树
mvn dependency:tree

# 按构件过滤
mvn dependency:tree -Dincludes=org.slf4j

# 输出到文件
mvn dependency:tree -DoutputFile=deps.txt

# 显示详细信息（含冲突解决过程）
mvn dependency:tree -Dverbose

分析依赖关系

# 查找未使用的已声明依赖和已使用但未声明的依赖
mvn dependency:analyze

# 仅显示问题项
mvn dependency:analyze-only

# 包含 test 作用域
mvn dependency:analyze -DignoreNonCompile=false

列出依赖

# 列出全部依赖
mvn dependency:list

# 按作用域筛选（例如仅 runtime）
mvn dependency:list -DincludeScope=runtime

冲突解决

Maven 默认策略

Maven 对版本冲突采用“最近定义优先（nearest definition wins）”策略：

A -> B -> C 1.0
A -> C 2.0

结果：使用 C 2.0（距根节点更近）

强制指定版本

    
        
        
            org.slf4j
            slf4j-api
            2.0.9
        
    

使用 Enforcer 插件进行版本管控

    
        
            org.apache.maven.plugins
            maven-enforcer-plugin
            3.4.1
            
                
                    enforce
                    
                        enforce
                    
                    
                        
                            
                            
                            
                        
                    
                
            
        
    

多模块项目

父 POM 的依赖管理

    com.example
    parent
    1.0.0
    pom

    
        
            
                com.example
                common
                ${project.version}
            
        
    




    
        com.example
        parent
        1.0.0
    

    module

    
        
        
            com.example
            common
        
    

仓库配置

中央仓库

    
        central
        https://repo.maven.apache.org/maven2
    

私有仓库

    
        company-repo
        https://nexus.company.com/repository/maven-public
        
            true
        
        
            true
        
    

settings.xml 中的仓库配置

    
        
            company-repo
            ${env.REPO_USER}
            ${env.REPO_PASS}
        
    

最佳实践

1. 使用 dependencyManagement —— 在父 POM 中集中管理版本
2. 导入 BOM —— 使用维护良好的框架 BOM 统一管理其依赖版本
3. 避免使用版本范围 —— 固定精确版本以保障构建可重现性
4. 定期更新依赖 —— 及时升级以修复安全漏洞
5. 最小化作用域 —— 合理选择作用域以减小最终包体积
6. 排除未使用依赖 —— 移除无用的传递性依赖
7. 注释排除原因 —— 明确说明为何需排除某依赖
8. 运行 dependency:analyze —— 定期检查依赖声明问题
9. 使用 Enforcer 插件 —— 强制保障依赖收敛性
10. 锁定版本 —— 使用 versions-maven-plugin 管理版本更新

常见陷阱

1. 版本冲突 —— 传递性依赖引入不同版本导致不一致
2. 遗漏排除 —— 不同构件中存在重复类（如多个 SLF4J 绑定）
3. 作用域误用 —— 混淆 compile / runtime / provided 等作用域语义
4. 依赖过时 —— 旧版本存在已知安全漏洞
5. 循环依赖 —— 模块 A 依赖 B，B 又依赖 A
6. 生产环境使用 SNAPSHOT —— 在正式发布中引入不稳定快照版本
7. system 作用域滥用 —— 硬编码本地路径破坏构建可移植性
8. optional 误用 —— 将实际必需的依赖标记为 optional

故障排查

调试依赖解析过程

# 启用调试输出
mvn dependency:tree -X

# 显示冲突解决详情
mvn dependency:tree -Dverbose=true

强制重新下载

# 清空本地仓库缓存
mvn dependency:purge-local-repository

# 强制更新远程依赖
mvn -U clean install

检查生效的 POM

# 查看经继承与插值后最终生效的依赖版本
mvn help:effective-pom

适用场景

• 向项目中添加新依赖
• 解决依赖版本冲突
• 搭建多模块项目的依赖结构
• 配置 BOM 导入
• 优化依赖树（减少冗余、裁剪体积）
• 排查类路径（classpath）相关问题
• 升级依赖版本
• 排除有问题的传递性依赖