Skip to content

Maven-依赖管理 ​

[TOC]

概述 ​

Apache Maven 是基于项目对象模型(Project Object Model,POM)的 Java 项目管理与构建工具。它将项目的元数据、依赖清单与构建流程统一收口到声明式的 pom.xml 中,核心解决依赖管理与标准化构建两大工程问题。本部分先从依赖管理视角切入,梳理 Maven 的设计背景、目录约定、整体架构、坐标定位与基础环境配置。

传统依赖痛点 ​

在引入构建工具之前,Java 项目(尤其是 Web 工程)通常手动将第三方 JAR 包复制到项目的 lib 或 WEB-INF/lib 目录并加入构建路径。随着项目规模扩大,手工维护方式会暴露出四个典型问题:

  1. 包体积膨胀与重复存储:每个项目各自拷贝一份相同的 JAR(如 MySQL 驱动、日志框架、JSON 库),不仅占用磁盘空间,还会导致版本控制系统(Git/SVN)仓库体积急剧膨胀。

  2. 传递依赖手工维护成本高:引入一个高层框架(如 Spring 或 MyBatis)时,往往隐含数十个底层依赖库,开发者必须逐一查找、下载并补齐缺失的 JAR,极易在运行期触发 ClassNotFoundException 或 NoClassDefFoundError。

  3. 版本冲突难以排查:当两个库依赖同一底层组件的不同版本时,手工放入 lib 目录的多个 JAR 会在类加载阶段产生不确定覆盖,排查冲突缺乏统一视图。

  4. 工程结构与构建流程割裂:不同开发者或 IDE(IntelliJ IDEA、Eclipse)创建的目录结构各异,编译、测试、打包高度依赖本地 IDE 图形化配置,难以在持续集成(CI)服务器上无差异复现。

Maven 通过声明式依赖替代物理拷贝:项目不再直接携带 JAR 文件,只在 pom.xml 中声明所需依赖的唯一坐标,由 Maven 自动完成下载、缓存、传递解析与类路径装配。

约定优于配置 ​

Maven 的核心设计哲学是约定优于配置(Convention over Configuration)。它为所有 Java 工程规定了一套统一的默认目录布局与构建规则;只要项目遵循该目录结构,无需额外编写路径配置即可直接执行编译、测试与打包。

text
demo-app/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   └── resources/
│   └── test/
│       ├── java/
│       └── resources/
└── target/

各目录承担固定职责,Maven 内置插件在执行阶段直接按约定路径读写文件:

目录或文件职责说明
pom.xml项目核心配置文件,定义坐标、依赖、插件与构建参数
src/main/java主业务 Java 源代码目录,编译目标为 target/classes
src/main/resources主业务配置文件目录(如 .properties、.xml),原样拷贝至 target/classes
src/test/java单元测试代码目录,编译目标为 target/test-classes,不打入最终产物
src/test/resources测试环境专用资源目录,原样拷贝至 target/test-classes
target构建输出根目录,存放编译字节码、测试报告与最终打包的 JAR/WAR 产物

遵循这套标准布局后,任意 IDE 只需导入 pom.xml 即可自动识别源码根目录、资源目录与测试目录,团队协作与命令行构建完全一致。

Maven 架构 ​

Maven 内部将项目模型、依赖仓库与构建引擎解耦协作。执行任意 mvn 命令时,Maven 核心引擎先融合全局配置 settings.xml 与项目配置 pom.xml 形成有效模型,再按坐标从本地仓库、镜像或远程仓库解析依赖并组装类路径,最终按生命周期调度插件完成构建输出。

image-20261120105014101

从依赖管理链路看,一次典型的构建启动会依次经过以下环节:

  1. 读取配置:加载用户级或全局 settings.xml(获取本地仓库路径、镜像与认证信息),解析当前工程的 pom.xml 并合并父 POM 与内置 Super POM。

  2. 定位依赖:根据 pom.xml 中声明的依赖坐标,优先检索本地仓库缓存。

  3. 远程拉取:若本地缺失对应构件(Artifact),按配置的镜像或远程仓库地址下载该构件的 .pom 描述文件与 .jar 包,并缓存至本地仓库。

  4. 传递解析与装配:递归读取依赖自身的 .pom 文件,展开传递依赖并执行版本仲裁,将最终确定的 JAR 集合装配到对应作用域的 Classpath 中供编译、测试或运行使用。

坐标体系 ​

GAV ​

Maven 仓库中存放着数以百万计的开源与内部构件,为了让每一个构件都能被全局唯一寻址,Maven 引入了坐标体系,核心由 groupId、artifactId、version 三个元素组成,简称 GAV。

  • groupId:定义当前项目隶属的组织或公司标识,通常采用域名倒写格式(如 org.apache.maven、com.google.code.gson)。它决定了构件在仓库中的顶层命名空间,避免不同组织发布同名项目时发生冲突。

  • artifactId:定义当前模块或构件的具体名称(如 gson、mysql-connector-j),在同一个 groupId 下必须唯一。它通常直接作为生成 JAR/WAR 文件名的前缀。

  • version:定义构件当前的版本号(如 2.11.0、1.0.0-SNAPSHOT)。其中带 -SNAPSHOT 后缀代表开发中的快照版本,不带该后缀代表不可变的正式发布版本(Release)。

辅助坐标与路径映射 ​

除必需的 GAV 外,坐标还可附带两个可选维度:

  • packaging:构件的打包类型(如 jar、war、pom),缺省值为 jar,决定构件文件扩展名以及绑定的默认生命周期插件。
  • classifier:用于区分同一 GAV 构建出的附属构件(如 sources 源码包、javadoc 文档包、适配不同操作系统的本地库),不会在项目自身坐标中直接声明,通常由构建插件附加生成。

Maven 依据 GAV 与 packaging 将逻辑坐标确定性地映射为本地与远程仓库中的物理目录路径,映射规则如下:

text
<仓库根目录>/<groupId按点拆分路径>/<artifactId>/<version>/<artifactId>-<version>[-<classifier>].<packaging>

例如坐标 com.google.code.gson:gson:2.11.0(默认 jar),在仓库中的精确文件路径即为:

text
com/google/code/gson/gson/2.11.0/gson-2.11.0.jar

Maven 安装 ​

在使用 Maven 构建项目之前,需在本地完成二进制包安装与环境变量配置,使任意终端与 IDE 都能通过 mvn 命令调用同一套构建工具。

环境前提与下载 ​

Maven 本身由 Java 编写,运行前必须先安装 JDK 并正确配置 JAVA_HOME 环境变量(Maven 3.9.x 最低要求 JDK 8,推荐使用 JDK 17 或 JDK 21)。

  1. 前往 Apache Maven 官网下载页获取二进制压缩包(Binary zip archive 适用于 Windows,Binary tar.gz archive 适用于 macOS/Linux,如 apache-maven-3.9.9-bin.zip)。

  2. 将压缩包解压至不含中文与空格的纯英文目录(例如 Windows 下的 D:\dev\apache-maven-3.9.9 或 Linux/macOS 下的 /usr/local/apache-maven-3.9.9),避免路径空格引发脚本或插件解析异常。

解压后根目录包含四个核心子目录:

目录作用说明
bin存放 mvn、mvnDebug 等可执行脚本(含 Windows .cmd 与 Unix Shell 版本)
boot存放 Plexus ClassWorlds 类加载框架 JAR,负责启动与隔离插件类加载器
conf存放全局级 settings.xml 与日志配置模板
lib存放 Maven 运行时核心依赖与内置组件 JAR

环境变量配置 ​

Windows 系统

  1. 打开「系统属性 → 高级 → 环境变量」,在系统变量中新建变量 MAVEN_HOME,变量值填写解压后的根目录(如 D:\Dev\apache-maven-3.9.9)。

  2. 编辑系统变量 Path,新增一条路径 %MAVEN_HOME%\bin 并保存。

macOS / Linux 系统

编辑当前 Shell 配置文件(~/.zshrc 或 ~/.bashrc),导出 MAVEN_HOME 并将 bin 目录追加至 PATH:

bash
# 1. 声明 Maven 解压后的安装根目录
export MAVEN_HOME=/usr/local/apache-maven-3.9.9

# 2. 将 bin 目录追加至系统 PATH
export PATH=$MAVEN_HOME/bin:$PATH

# 3. 使环境变量配置立即生效
source ~/.zshrc

安装验证 ​

重新打开一个终端窗口(确保读取最新环境变量),执行版本检查命令:

bash
# 1. 查看 Maven 版本、安装路径及绑定的 JDK 版本
mvn -v

若控制台正常打印如下信息,且 Maven home 与 Java version 均指向预期安装目录,说明本地安装成功:

text
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: D:\Dev\apache-maven-3.9.9
Java version: 17.0.12, vendor: Eclipse Adoptium, runtime: D:\dev\jdk-17
Default locale: zh_CN, platform encoding: UTF-8
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

settings.xml ​

安装 JDK 与 Maven 并配置 MAVEN_HOME、PATH 环境变量后,通常只需在 settings.xml 中完成两项入门配置即可投入使用:指定本地仓库目录与配置国内镜像源。

Maven 存在两处 settings.xml:安装目录下 conf/settings.xml 为全局配置,用户主目录下 ~/.m2/settings.xml 为用户级配置。两者同时存在时,用户级配置会覆盖全局配置中的同名项,推荐优先维护 ~/.m2/settings.xml 以避免升级 Maven 时丢失设置。

xml
<!-- 1. Maven 全局或用户级环境配置文件(通常位于 ~/.m2/settings.xml) -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">

  <!-- 2. 自定义本地仓库目录,避免默认占用系统盘空间 -->
  <localRepository>D:/Dev/.m2/repository</localRepository>

  <mirrors>
    <!-- 3. 配置国内镜像仓库,加速依赖下载 -->
    <mirror>
      <id>aliyunmaven</id>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>

      <!-- 4. 拦截指向中央仓库 central 的所有依赖请求 -->
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

  <profiles>
    <!-- 5. 配置JDK编译版本(可选) -->
    <profile>
        <id>jdk-17</id>
        <activation>
          <activeByDefault>true</activeByDefault>
          <jdk>17</jdk>
        </activation>
        <properties>
          <maven.compiler.source>17</maven.compiler.source>
    	  <maven.compiler.target>17</maven.compiler.target>
          <maven.compiler.compilerVersion>17</maven.compiler.compilerVersion>
        </properties>
    </profile>
  </profiles>
</settings>

上述配置将依赖缓存路径固定到独立目录,并把发往默认中央仓库 central 的请求重定向至镜像地址,显著缩短首次下载依赖的等待时间。关于多仓库检索顺序、私服配置及快照更新策略,将在后续「仓库管理」章节深入展开。

IDEA 集成 ​

IntelliJ IDEA 默认内置了一个捆绑版 Maven,但为了保证 IDE 内构建结果与命令行完全一致,建议将 IDEA 指向本机手动安装的 Maven 与自定义 settings.xml:

  1. 为了让 IDEA 中的所有项目都生效,在绑定 Maven 之前需要先关闭所有项目,然后打开 Customize → All settions → Build, Execution, Deployment → Build Tools → Maven。

  2. 如果只是想对当前项目生效,可以打开 Settings → Build, Execution, Deployment → Build Tools → Maven。

  3. 将 Maven home path 修改为本机解压的 Maven 根目录(如 D:\dev\apache-maven-3.9.9)。

  4. 勾选 User settings file 右侧的 Override,指定配置好本地仓库与国内镜像的 settings.xml 路径;下方的 Local repository 会随之自动刷新为配置文件中的目录。

  5. 若希望后续所有新建工程默认沿用上述路径,需同步在 File → New Projects Setup → Settings for New Projects 中完成相同配置。

创建 Maven Web 项目 ​

Java Web 工程的交付物是可部署至 Servlet 容器(如 Tomcat)的 WAR(Web Application Archive)包。与普通 JAR 工程相比,Maven Web 工程在目录约定、打包类型与容器规范依赖的作用域上有明确差异。

Web 工程目录结构 ​

在标准目录布局基础上,Web 工程在 src/main/ 下新增 webapp 作为 Web 资源根目录:

text
maven-web-demo/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/example/web/
    │   │       └── HelloServlet.java
    │   ├── resources/
    │   └── webapp/
    │       ├── index.jsp
    │       └── WEB-INF/
    │           └── web.xml
    └── test/
        ├── java/
        └── resources/

新增目录与文件的职责如下:

目录或文件职责说明
src/main/webappWeb 应用根目录,存放 HTML、CSS、JavaScript、图片与 JSP 等页面资源,打包时原样平铺至 WAR 包根目录
src/main/webapp/WEB-INF受容器保护的私有目录,客户端浏览器无法通过 URL 直接访问其内部文件
src/main/webapp/WEB-INF/web.xmlWeb 应用部署描述符,用于声明 Servlet 规范版本、过滤器、监听器、错误页与欢迎页

工程创建方式 ​

命令行骨架生成 ​

可通过官方提供的 maven-archetype-webapp 骨架快速生成 Web 工程基础结构,附加 -DarchetypeCatalog=internal 可直接读取本地内置骨架清单,避免联网拉取远程目录造成长时间卡顿:

bash
# 1. 使用官方 Web 骨架生成工程,附加 internal 参数跳过远程目录拉取以提速
mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=maven-web-demo \
  -DarchetypeArtifactId=maven-archetype-webapp \
  -DarchetypeCatalog=internal \
  -DinteractiveMode=false

使用该官方骨架需注意两处历史遗留问题:一是生成的目录默认缺少 src/main/java、src/main/resources 与 src/test/java,需手工补齐;二是自动生成的 web.xml 仍停留在古老的 Servlet 2.3 DTD 声明,默认关闭 EL 表达式解析,建完工程后必须立即升级为 Servlet 4.0(或 Jakarta Servlet 5.0/6.0)的 XSD 约束头。

IDEA 创建 ​
  1. 通过 New Project 选择 Maven(或直接在 Maven Archetype 中选择 org.apache.maven.archetypes:maven-archetype-webapp)创建工程并填写 GAV 坐标。

  2. 若从空白 Maven 工程起步,直接在 pom.xml 中将 <packaging> 改为 war,并在 src/main/ 下新建 webapp/WEB-INF/web.xml 后点击 Maven 面板的刷新按钮,IDEA 会自动识别并装配 Web Facet 与 WAR Artifact。

pom.xml 配置 ​

Web 工程的核心配置要点包括:声明 <packaging>war</packaging>、以 provided 作用域引入 Servlet API,以及锁定 maven-compiler-plugin 与 maven-war-plugin 版本。以下示例适配 Tomcat 9(Servlet 4.0);若目标容器为 Tomcat 10 及以上版本,需将依赖坐标替换为 jakarta.servlet:jakarta.servlet-api(6.0+)并同步改用 jakarta.servlet.* 包路径。

xml
<!-- 1. 声明 Maven Web 工程,核心是将 packaging 指定为 war -->
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>maven-web-demo</artifactId>
  <version>1.0.0</version>
  <!-- 2. 指定打包方式为 war,自动绑定 maven-war-plugin -->
  <packaging>war</packaging>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <!-- 3. 引入 Servlet API,作用域必须设为 provided 以免与 Tomcat 容器冲突 -->
  <dependencies>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>4.0.1</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <!-- 4. 配置最终产物名称与编译、WAR 打包插件版本 -->
  <build>
    <finalName>maven-web-demo</finalName>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
      </plugin>

      <!-- 5. 锁定 WAR 打包插件版本;使用纯注解配置时可关闭 web.xml 强制检查 -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.4.0</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

编写 Servlet 与 web.xml ​

将 src/main/webapp/WEB-INF/web.xml 更新为 Servlet 4.0 标准声明:

xml
<!-- 1. 声明 Servlet 4.0 规范头(替代 archetype 生成的旧版 2.3 DTD) -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

  <!-- 2. 定义默认欢迎页 -->
  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>

</web-app>

在 src/main/java/com/example/web/HelloServlet.java 中编写最小验证入口:

java
package com.example.web;

import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// 1. 使用注解映射请求路径,无需在 web.xml 中手写 servlet 映射
@WebServlet("/hello")
public class HelloServlet extends HttpServlet {

  // 2. 处理 HTTP GET 请求
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {

    // 3. 设置响应内容类型与字符集,防止中文乱码
    resp.setContentType("text/plain;charset=UTF-8");

    // 4. 输出响应文本至客户端
    resp.getWriter().write("Hello Maven Web");
  }
}

打包与部署验证 ​

在工程根目录执行打包命令,并检查 WAR 包内部目录结构:

bash
# 1. 清理历史构建并打包生成 WAR 文件与解压目录
mvn clean package

# 2. 查看 WAR 包内部目录清单,确认 provided 依赖未被误打入 WEB-INF/lib
jar -tf target/maven-web-demo.war

执行完成后,可在 target/ 目录下看到 maven-web-demo.war 压缩归档包以及同名展开目录 target/maven-web-demo/:

  • 编译后的 HelloServlet.class 与资源文件已自动归入 WEB-INF/classes/。
  • 所有 compile 与 runtime 依赖被自动收集至 WEB-INF/lib/,而声明为 provided 的 javax.servlet-api 不会出现在包内。
  • 将 target/maven-web-demo.war 拷贝至 Tomcat 的 webapps/ 目录启动,或在 IntelliJ IDEA 中配置本地 Tomcat Server 挂载 maven-web-demo:war exploded 工件启动后,访问 http://localhost:8080/maven-web-demo/hello 即可看到响应输出 Hello Maven Web。

示例: 标准依赖引入 ​

下面构建一个最小的可运行 Maven 工程,演示如何仅通过声明 pom.xml 引入第三方库 Gson 并完成编译验证。

pom.xml 配置 ​

在工程根目录创建 pom.xml,声明自身 GAV 坐标、JDK 编译版本以及 gson 依赖:

xml
<!-- 1. 声明 POM 模型版本与根元素 -->
<project xmlns="http://maven.apache.org/POM/4.0.0">

  <modelVersion>4.0.0</modelVersion>

  <!-- 2. 定义当前工程的 GAV 坐标与打包方式 -->
  <groupId>com.example</groupId>
  <artifactId>maven-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <!-- 3. 声明编译期 JDK 版本与源码字符集 -->
  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <!-- 4. 声明外部依赖,Maven 自动按 GAV 解析并下载 JAR -->
  <dependencies>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.11.0</version>
    </dependency>
  </dependencies>

</project>

业务源码 ​

按照约定目录结构,在 src/main/java/com/example/App.java 中直接调用 Gson API,无需手动向项目目录拷贝任何 JAR 文件:

java
package com.example;

import com.google.gson.Gson;
import java.util.Map;

// 1. 定义入口类,验证 Maven 自动引入的 Gson 依赖可直接参与编译与运行
public class App {

  // 2. 启动主方法,构造数据并序列化为 JSON 字符串
  public static void main(String[] args) {
    Gson gson = new Gson();
    Map<String, String> project = Map.of("name", "maven-demo", "tool", "Maven");

    // 3. 调用外部依赖库 Gson 完成序列化
    String json = gson.toJson(project);

    // 4. 输出序列化结果
    System.out.println(json);
  }
}

命令验证 ​

在包含 pom.xml 的根目录下执行以下命令,验证依赖拉取、自动编译与依赖树解析:

bash
# 1. 下载依赖并编译 src/main/java,产物输出至 target/classes
mvn compile

# 2. 查看当前工程已解析的完整依赖树
mvn dependency:tree

执行 mvn compile 后,Maven 会自动从仓库下载 gson-2.11.0.jar 及其传递依赖,并将 App.java 编译输出到 target/classes/com/example/App.class。执行 mvn dependency:tree 可以在控制台直接观测到当前工程声明的直接依赖与自动展开的传递依赖层级。

POM ​

项目对象模型(Project Object Model,POM) 是 Maven 工程的核心元数据文件。它通过声明式的 XML 规范定义了项目的组织坐标、构建属性、依赖管理规则、生命周期绑定插件以及多模块层级关系。Maven 的所有自动化构建与依赖解析行为,本质上都是围绕对 pom.xml 的解析与模型合并展开的。

project ​

根节点与模型版本 ​

pom.xml 的根节点为 <project>,其下包含的模型版本与核心元数据决定了当前构件的基本身份与物理打包行为。

<project> 必须声明 Maven 4.0.0 的 XML 命名空间(Namespace)与 Schema 校验约束,其子节点 <modelVersion> 固定为 4.0.0,代表遵循 Maven 2/3/4 的标准对象模型:

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!-- ... -->
</project>

核心元数据元素 ​

在根元素下,除必需的 GAV 坐标外,还包括决定打包形态与项目说明的元数据:

  • <groupId>:组织机构标识,通常为逆向域名。
  • <artifactId>:项目或模块名,构成最终打包文件名的前缀。
  • <version>:版本号,遵循 主版本.次版本.修订号[-限定符] 规范。
  • <packaging>:打包类型,核心取值包括:
    • jar(默认,Java 类库或应用);
    • war(Java Web 应用);
    • pom(仅作为父工程或聚合工程,不产生实体 JAR)。
  • <name>:对用户友好的项目显示名称,常用于构建日志与文档。
  • <description>:项目的简要业务或功能描述。
  • <url>:项目官网或源码仓库托管地址。

dependencies ​

<dependencies> 是项目引入外部库的核心容器,包含多个 <dependency> 节点。

依赖元数据字段 ​

每个依赖项通过以下元素精细化控制其解析行为:

  • <groupId>、<artifactId>、<version>:目标依赖的精确 GAV 坐标。
  • <type>:依赖构件的类型,默认为 jar,在引入 BOM 或共享测试包时可指定为 pom 或 test-jar。
  • <classifier>:用于区分附加构建物,例如 sources(源码包)或 linux-x86_64(平台特定包)。
  • <scope>:依赖作用域(如 compile、provided、runtime、test、system、import),控制依赖在编译、测试、打包等阶段的 Classpath 可见性。
  • <optional>:标记是否为可选依赖(true 或 false)。声明为 true 的依赖不会被下游项目自动传递引入。

排除传递依赖 ​

当引入的第三方库隐式引入了不兼容、冗余或冲突的底层依赖时,可通过 <exclusions> 元素显式切断其传递链:

xml
<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>3.6.1</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
        </exclusion>
    </exclusions>
</dependency>

在排除声明中,只需指定 groupId 与 artifactId,无需指定版本号,该依赖下所有版本的对应构件均会被拦截。

properties ​

Maven 提供了灵活的属性(Properties)机制,通过 <properties> 声明自定义常量,并通过 ${property.name} 语法在 POM 中进行变量插值替换,避免硬编码。

属性类型分类 ​

Maven 运行时支持五类核心属性解析:

  1. 自定义属性:在 <properties> 块中自定义的标签,如 <spring.version>6.1.5</spring.version>,通过 ${spring.version} 引用。

  2. 项目模型属性:以 project. 为前缀,引用 pom.xml 中任意节点的值。

    • ${project.groupId}、${project.artifactId}、${project.version}:当前模块坐标。
    • ${project.basedir}:当前模块根目录的绝对路径。
    • ${project.build.directory}:构建输出目录,默认即 target。
  3. 系统环境变量:以 env. 为前缀,引用操作系统环境变量,如 ${env.JAVA_HOME}、${env.M2_HOME}。

  4. Java 系统属性:直接引用 JVM 运行时系统变量,如 ${user.home}、${file.encoding}、${java.version}。

  5. 设置文件属性:以 settings. 为前缀,引用 settings.xml 中的配置,如 ${settings.localRepository}。

dependencyManagement ​

在多模块工程或微服务架构中,直接在子模块中硬编码版本号会导致版本碎片化与冲突。Maven 通过 <dependencyManagement> 提供了集中版本管控机制。

依赖版本声明与引入解耦 ​

  • <dependencyManagement>(版本池):仅负责声明依赖的 GAV 坐标、版本、作用域及排除规则,不会在当前项目中实际引入物理 JAR,也不会触发下载。它充当一个“依赖配置池”。
  • <dependencies>(物理引入):子模块实际引入依赖时,只需声明 groupId 与 artifactId,无需编写 <version>。Maven 会自动匹配并继承父 POM 或 BOM 中 <dependencyManagement> 指定的版本。

BOM 导入机制 ​

通过在 <dependencyManagement> 中声明 scope 为 import、type 为 pom,可以将外部标准清单(Bill of Materials,BOM)引入当前工程,实现多框架组件的一致性版本同步:

xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

继承与聚合结构 ​

为了复用配置并支持多模块批量构建,Maven 设计了继承(Inheritance) 与聚合(Aggregation) 两种组织模型。

image-20261120105042531

继承机制 ​

子 POM 通过 <parent> 显式声明其父工程坐标,并可通过 <relativePath> 指定父 POM 的磁盘相对路径(默认为 ../pom.xml):

xml
<parent>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0.0</version>
    <relativePath>../pom.xml</relativePath>
</parent>
Super POM 隐式继承 ​

任何 Maven 工程即便没有显式声明 <parent>,都会隐式继承 Maven 内置的 Super POM(位于 Maven 核心包的 pom-4.0.0.xml)。Super POM 定义了默认的中央仓库地址、默认插件版本(如 maven-compiler-plugin)、标准目录布局(src/main/java 等)以及默认构建输出目录 target。

可继承元素清单 ​

子 POM 从父 POM 继承的内容包括:

  • <properties> 自定义属性
  • <dependencies> 物理依赖
  • <dependencyManagement> 依赖管理池
  • <build> 插件配置及插件管理(<pluginManagement>)
  • <repositories> 仓库配置

聚合机制 ​

聚合工程(Aggregator) 通常打包方式为 <packaging>pom</packaging>,通过 <modules> 声明其管理的子模块相对路径:

xml
<modules>
    <module>order-core</module>
    <module>order-api</module>
    <module>order-service</module>
</modules>

在聚合工程根目录下执行 mvn 构建命令时,Maven 会分析各模块之间的依赖拓扑顺序(Reactor Sort),并按拓扑依赖顺序串行或并行构建所有子模块。

继承与聚合对比 ​

维度继承 (Inheritance)聚合 (Aggregation)
核心目的消除配置冗余,复用依赖、插件与属性统一构建入口,一键批量构建多子模块
配置元素子模块配置 <parent> 指向父模块聚合模块配置 <modules> 包含子模块路径
打包方式父模块必须是 pom;子模块可以是任意类型聚合模块必须是 pom
依赖方向子 POM 显式感知并引用父 POM聚合 POM 感知子模块,子模块可不感知聚合 POM
物理目录子模块通常位于父目录下一级(非强制)子模块通常作为聚合目录的子文件夹

在实际工程中,通常将父工程同时设计为聚合工程,即在同一个 pom.xml 中同时定义 <modules> 与 <dependencyManagement>。

示例: 完整项目 POM 配置 ​

以下是一个企业级标准单体/父级模块 pom.xml 示例,集中展示了坐标、元数据、继承自 Spring Boot Parent、属性定义、依赖管理、排除机制与实际依赖声明:

xml
<!-- 1. 声明项目基础元数据与父级继承 -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <!-- 2. 当前项目坐标标识 -->
    <groupId>com.example</groupId>
    <artifactId>order-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>Order Service</name>
    <description>订单微服务模块</description>

    <!-- 3. 全局属性声明与版本集中定义 -->
    <properties>
        <java.version>17</java.version>
        <spring-cloud.version>2023.0.1</spring-cloud.version>
        <mybatis-plus.version>3.5.6</mybatis-plus.version>
    </properties>

    <!-- 4. 依赖版本管理声明(仅定义版本,不引入物理依赖) -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- 5. 实际引入的依赖集合 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
        </dependency>

        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
            <version>${mybatis-plus.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.mybatis</groupId>
                    <artifactId>mybatis-spring</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

仓库管理 ​

Maven 仓库(Repository)是集中存储项目构件(Artifact,如 JAR、WAR、POM 文件)及其元数据(Metadata)的逻辑与物理容器。通过将构件从各个工程目录抽离并统一托管到多级仓库体系中,Maven 实现了依赖的按需拉取、本地复用以及企业内部的构件共享发布。

仓库分类 ​

Maven 将仓库划分为本地仓库与远程仓库两大阵营,其中远程仓库进一步细分为中央仓库、私服与第三方公共仓库。

本地仓库 ​

本地仓库位于开发者本机磁盘中,默认路径为 ~/.m2/repository(可通过 settings.xml 中的 <localRepository> 修改)。它是当前主机上所有 Maven 工程共享的唯一本地缓存区,构件来源主要有两条:

  1. 远程下载缓存:解析外部依赖时,从远程仓库拉取的 .pom、.jar 及校验文件会自动沉淀至本地仓库,后续其他项目引用相同 GAV 时直接复用。

  2. 本地构建安装:在本地工程执行 mvn install 后,当前项目的打包产物会被安装进本地仓库,供本机其他模块作为依赖引用。

在本地仓库的每个版本目录下,除了 .jar 和 .pom 文件外,Maven 还会自动生成一个 _remote.repositories 文件,用于记录该构件最初从哪一个仓库 id 下载而来。若将他人的本地仓库直接拷贝到本机且双方 settings.xml 中的镜像 id 不一致,Maven 会判定缓存来源不匹配并尝试重新联网校验;遇到该问题时,可删除目录下的 _remote.repositories 文件,或在命令行附加 -llr(--legacy-local-repository)跳过来源校验。

中央仓库 ​

中央仓库(Central Repository)由 Maven 社区官方维护,默认定义在所有项目隐式继承的 Super POM 中,仓库标识固定为 central,地址为 [https://repo.maven.apache.org/maven2](https://repo.maven.apache.org/maven2)。中央仓库托管了绝大多数开源 Java 类库与 Maven 官方插件,具有两项默认特征:

  • 只读公共源:普通开发者只能从中下载,不能直接执行 mvn deploy 上传构件。
  • 仅托管正式版:Super POM 默认关闭了中央仓库的快照版(Snapshot)检索,只允许拉取稳定的 Release 版本。

私服 ​

私服(Repository Manager,常用工具为 Sonatype Nexus 与 JFrog Artifactory)是部署在企业局域网内的专用远程仓库服务。在团队研发中,私服同时承担三项核心职责:

  • 代理缓存外部仓库:团队所有开发机统一向私服请求开源依赖;若私服尚未缓存,则由私服代理访问外网中央仓库并缓存,大幅节约外网带宽并加快全员构建速度。
  • 托管内部私有构件:承接企业内部通用基础库、公共 DTO 或二方包的发布(Release 与 Snapshot),实现跨项目协同。
  • 收纳受限第三方包:托管因商业许可限制未上架中央仓库的组件(如部分商业数据库驱动或厂商 SDK)。

在 Nexus 内部,通常会把宿主仓库(Hosted,存放内部发布包)与代理仓库(Proxy,缓存中央仓库等外部源)聚合为一个仓库组(Group,如 maven-public),对外暴露单一 URL 供客户端统一拉取。

第三方公共仓库 ​

除中央仓库外,部分开源组织(如 Spring Milestone、JBoss、阿里云公共库)或云厂商会独立搭建公共远程仓库。当所需组件尚未同步至中央仓库时,可在 pom.xml 的 <repositories> 或 settings.xml 的 <profile> 中显式追加这些第三方仓库地址。

仓库检索流程 ​

当 Maven 解析一个依赖坐标或执行插件目标时,并不会盲目访问互联网,而是遵循严格的本地优先、镜像拦截与多级回退检索链路。

image-20261120105109171

一次完整的构件检索流程如下:

  1. 构建有效仓库列表:合并当前 pom.xml、父 POM、已激活的 profile 以及 Super POM 中声明的远程仓库列表(普通依赖读取 <repositories>,Maven 插件独立读取 <pluginRepositories>)。

  2. 查询本地仓库:根据 GAV 计算物理路径,检查本地仓库中是否已存在目标构件。

  3. 判定缓存有效性:若目标为 Release 版本且本地已存在有效缓存,直接命中并返回;若目标为 Snapshot 版本,则结合 <updatePolicy> 判断本地快照是否过期。

  4. 执行 Mirror 拦截:当本地未命中或快照需要更新时,Maven 遍历候选远程仓库,逐一与 settings.xml 中的 <mirrorOf> 规则比对;一旦命中镜像规则,原始仓库 URL 会被完全替换为镜像地址,不再直连原仓库。

  5. 远程拉取与校验:向目标镜像或远程仓库发起 HTTP/HTTPS 请求,下载构件文件(.pom、.jar)及其摘要文件(.sha1、.md5),按 <checksumPolicy> 校验文件完整性。

  6. 落盘缓存与装配:校验通过后将构件与 _remote.repositories 写入本地仓库,随后装配至构建 Classpath。若所有候选仓库均无法找到目标构件,则在本地写入 .lastUpdated 缓存标记文件,防止短时间内重复无效请求,并抛出依赖解析失败错误。

构件版本策略 ​

Maven 仓库根据版本是否可变,将构件划分为 Release 与 Snapshot 两大体系,并配套独立的更新与校验策略。

Release ​

正式发布版本(如 2.11.0、3.2.5)在语义上是不可变的(Immutable)。一旦某个 Release 坐标被发布到远程仓库并下载至开发机本地,Maven 默认认定该版本内容永远不会再发生变化,后续构建不会再向远程仓库发起更新检查。若确实需要修改代码,必须递增版本号重新发布。

Snapshot ​

快照版本以 -SNAPSHOT 结尾(如 1.0.0-SNAPSHOT),专用于开发联调阶段的频繁迭代。当模块 A 处于活跃开发期,而模块 B 依赖模块 A 时,使用 Snapshot 可以避免每次微小改动都修改版本号。

当执行 mvn deploy 将 1.0.0-SNAPSHOT 发布到私服时,Maven 会自动将其展开为带时间戳与构建序号的唯一文件名(例如 order-core-1.0.0-20261119.083012-3.jar),并同步更新仓库目录下的 maven-metadata.xml 索引文件。下游项目在拉取 1.0.0-SNAPSHOT 时,Maven 会先读取 maven-metadata.xml 定位最新的时间戳版本并下载至本地。

更新策略 ​

仓库对构件(尤其是 Snapshot)的远程检查频率由 <updatePolicy> 控制,取值如下:

取值检查行为
daily默认策略,每天仅向远程仓库检查一次更新
always每次执行构建命令时都向远程仓库检查最新版本
interval:X按指定间隔检查更新,单位为分钟(如 interval:60)
never从不主动检查更新,仅在本地完全缺失时下载

在命令行中追加 -U(--update-snapshots)参数,可以临时覆盖配置中的 <updatePolicy>,强制本次构建立即检查并拉取远程最新快照,同时清理此前下载失败残留的 .lastUpdated 标记。

校验策略 ​

远程下载构件时,Maven 通过对比服务端提供的 .sha1 或 .md5 摘要文件防止网络传输损坏或文件篡改。校验失败时的处理方式由 <checksumPolicy> 控制:

  • warn:默认策略,在控制台输出警告日志但继续构建。
  • fail:校验不通过时立即中止构建,适合对产物一致性要求严格的持续集成环境。
  • ignore:完全跳过校验和验证。

下面演示在 pom.xml 中为自定义仓库分别配置 Release 与 Snapshot 的启用开关、更新策略与校验策略:

xml
<!-- 1. 在 pom.xml 中声明自定义远程仓库及其版本策略 -->
<repositories>
  <repository>
    <id>company-nexus</id>
    <name>企业私服仓库组</name>
    <url>https://nexus.example.com/repository/maven-public/</url>

    <!-- 2. 开启正式版下载并设置每日检查更新 -->
    <releases>
      <enabled>true</enabled>
      <updatePolicy>daily</updatePolicy>
      <checksumPolicy>warn</checksumPolicy>
    </releases>

    <!-- 3. 开启快照版下载并设置每次构建强制检查最新时间戳版本 -->
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
      <checksumPolicy>fail</checksumPolicy>
    </snapshots>
  </repository>
</repositories>

Mirror ​

镜像(Mirror) 用于拦截发往指定远程仓库的下载请求,并将其重定向至速度更快、网络更稳定的替代仓库(如阿里云公共仓库或企业内网 Nexus)。镜像只能在 settings.xml 的 <mirrors> 节点中配置,因为镜像属于与当前运行环境网络拓扑绑定的全局设置,不应硬编码在项目 pom.xml 中。

匹配规则 ​

<mirrorOf> 决定了当前镜像会拦截哪些远程仓库的请求,支持通配符与排除语法:

<mirrorOf> 表达式拦截范围说明
central仅拦截 Super POM 中默认的中央仓库
*拦截所有远程仓库,包括 pom.xml 中额外声明的第三方仓库与本地 file:// 仓库
external:*拦截所有非本机(非 localhost 且非 file:// 协议)的远程仓库
repoA,repoB精确拦截 id 为 repoA 或 repoB 的多个指定仓库
*,!special-repo拦截除 special-repo 之外的所有远程仓库

使用镜像时需要注意两个典型边界:

  1. 谨慎使用全局通配符 \*:若将 <mirrorOf>设为_并指向仅代理中央仓库的公网镜像,项目中单独配置的私有仓库或特定开源仓库请求也会被一并截走,导致私有依赖找不到。此时应使用external:_,!<repoId>放行特定仓库,或在企业内部统一将\* 指向已经聚合全部上游代理的 Nexus 仓库组。

  2. 默认 HTTP 拦截保护:自 Maven 3.8.1 起,安装目录 conf/settings.xml 中内置了名为 maven-default-http-blocker 的安全镜像(<mirrorOf>external:http:*</mirrorOf> 且 <blocked>true</blocked>),会自动拦截所有明文 http:// 协议的外部仓库访问。若企业内网私服仍使用 HTTP 协议,需升级至 HTTPS,或在用户级 ~/.m2/settings.xml 中针对该私服配置显式镜像以绕过默认拦截器。

xml
<!-- 1. 在 settings.xml 中配置私服镜像拦截 -->
<mirrors>
  <mirror>
    <id>nexus-public</id>
    <name>企业内部 Nexus 仓库组</name>
    <url>https://nexus.example.com/repository/maven-public/</url>

    <!-- 2. 拦截所有非本地的远程仓库,但排除特殊第三方仓库 special-repo -->
    <mirrorOf>external:*,!special-repo</mirrorOf>
  </mirror>
</mirrors>

仓库认证 ​

访问受权限保护的企业私服,或向远程仓库发布构建产物时,需要提供用户名、密码或私钥凭据。出于安全考虑,认证信息严禁写入随源码提交到 Git 的 pom.xml,而必须集中存放在本机 settings.xml 的 <servers> 节点下。

Maven 通过严格比对 <id> 字段 来完成凭据绑定:

  • 下载认证:<server> 中的 <id> 必须与 pom.xml 中的 <repository>/<id> 或 settings.xml 中的 <mirror>/<id> 完全一致。
  • 发布认证:<server> 中的 <id> 必须与 pom.xml 中 <distributionManagement> 下对应仓库的 <id> 完全一致。

为了避免在 settings.xml 中明文存放密码,Maven 提供了内置加密机制:先执行 mvn --encrypt-master-password 生成主密钥并保存至 ~/.m2/settings-security.xml,再执行 mvn --encrypt-password 对仓库密码加密,将形如 {COQLCE6DU6GtcS5P=} 的密文填入 <password> 节点即可。

构件发布 ​

完成模块开发与测试后,Maven 提供两种将构建产物输出到仓库的命令:

  • mvn install:将当前项目的产物及 .pom 文件安装至本机本地仓库,仅本机可见。
  • mvn deploy:在完成本地安装后,依据 pom.xml 中 <distributionManagement> 的目标地址,将产物与元数据自动推送至远程私服,供团队成员与持续集成流水线拉取。

<distributionManagement> 内部通常同时声明两个目标节点:

  1. <repository>:接收不带 -SNAPSHOT 后缀的正式版本构件,对应私服中的 Releases 宿主仓库。

  2. <snapshotRepository>:接收带 -SNAPSHOT 后缀的快照版本构件,对应私服中的 Snapshots 宿主仓库。

执行 mvn deploy 时,Maven 会根据当前项目 <version> 是否以 -SNAPSHOT 结尾自动路由至对应仓库,并在上传前依据 <id> 自动加载 settings.xml 中的认证凭据。

示例: 私服配置与发布 ​

下面通过完整的 settings.xml、pom.xml 与命令行操作,演示团队开发机如何接入企业 Nexus 私服并发布内部构件。

settings.xml 配置 ​

在 ~/.m2/settings.xml 中配置本地仓库路径、私服发布凭据以及统一镜像代理:

xml
<!-- 1. 企业级 ~/.m2/settings.xml 私服接入与认证配置 -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">

  <!-- 2. 指定本地仓库缓存路径 -->
  <localRepository>D:/maven/repository</localRepository>

  <!-- 3. 配置私服发布与拉取凭据,id 必须与仓库或镜像 id 严格一致 -->
  <servers>
    <server>
      <id>nexus-releases</id>
      <username>deployer</username>
      <password>{COQLCE6DU6GtcS5P=}</password>
    </server>

    <server>
      <id>nexus-snapshots</id>
      <username>deployer</username>
      <password>{COQLCE6DU6GtcS5P=}</password>
    </server>
  </servers>

  <!-- 4. 将全部外部仓库请求统一代理至企业 Nexus 仓库组 -->
  <mirrors>
    <mirror>
      <id>nexus-public</id>
      <mirrorOf>*</mirrorOf>
      <url>https://nexus.example.com/repository/maven-public/</url>
    </mirror>
  </mirrors>

</settings>

pom.xml 发布配置 ​

在需要对外共享的父工程或公共基础库的 pom.xml 中配置 <distributionManagement>,将其 <id> 与上方 <server> 一一对应:

xml
<!-- 1. 在 pom.xml 中声明构件发布目标仓库 -->
<distributionManagement>

  <!-- 2. 正式版发布目标,id 需与 settings.xml 中的 server id 匹配 -->
  <repository>
    <id>nexus-releases</id>
    <name>Nexus Releases Repository</name>
    <url>https://nexus.example.com/repository/maven-releases/</url>
  </repository>

  <!-- 3. 快照版发布目标,版本号带 -SNAPSHOT 后缀时自动路由至此 -->
  <snapshotRepository>
    <id>nexus-snapshots</id>
    <name>Nexus Snapshots Repository</name>
    <url>https://nexus.example.com/repository/maven-snapshots/</url>
  </snapshotRepository>

</distributionManagement>

常用仓库操作命令 ​

在工程根目录执行对应命令,完成本地安装、快照强制刷新与私服发布:

bash
# 1. 仅将当前构建产物安装至本地仓库,供本机其他模块引用
mvn clean install

# 2. 强制刷新远程仓库中的 Snapshot 快照版本并重新编译打包
mvn clean package -U

# 3. 将构建产物上传至 distributionManagement 指定的私服仓库
mvn clean deploy

依赖作用域 ​

依赖作用域(Dependency Scope)通过 pom.xml 中 <dependency> 下的 <scope> 元素声明,用于精确限定某个依赖在构建各阶段的可见边界。它直接决定三项工程行为:该依赖进入哪几套 Classpath、是否被打入最终发布包(如 WAR 的 WEB-INF/lib 或 Fat JAR),以及是否会继续向下游模块传递。

Classpath 隔离模型 ​

Maven 在构建一个 Java 工程时,并非把所有声明的 JAR 混入同一份类路径,而是按阶段维护三套相互隔离的 Classpath:

  1. 编译 Classpath(Compile Classpath):执行 mvn compile 编译 src/main/java 主业务源码时使用的类路径。

  2. 测试 Classpath(Test Classpath):执行 mvn test-compile 与 mvn test 编译并运行 src/test/java 单元测试时使用的类路径。

  3. 运行 Classpath(Runtime Classpath):程序打包发布并实际启动运行时加载的类路径,决定哪些依赖需要随应用一同打包分发。

image-20261120105133454

将依赖隔离到不同 Classpath,既能防止单元测试库污染生产发布包体积,也能避免 Web 容器自带规范包(如 Servlet API)被重复打包进而引发运行期类加载冲突。

六类作用域 ​

Maven 规范共定义了六种依赖作用域,分别对应不同的工程生命周期需求。

compile ​

compile 是 <scope> 缺省时的默认作用域。该作用域的依赖在编译、测试、运行三套 Classpath 中全部生效,会被打入最终发布包,并且默认具备传递性。

日常业务开发所依赖的核心工具库与框架组件(如 gson、spring-context、commons-lang3)均使用 compile。

provided ​

provided 表示该依赖在编译与测试 Classpath 中有效,但在运行 Classpath 中失效,不会被打包进最终产物,且不具备传递性。它向 Maven 声明:目标运行环境(JDK 或 Servlet 容器)在部署期已经内置了该类库。

典型场景包括两类:

  1. 容器内置规范 API:如 javax.servlet-api 或 jakarta.servlet-api。编码与编译阶段必须依赖其接口定义,但部署到 Tomcat 等容器后由容器自身提供实现,打包进 WAR 反而会造成冲突。

  2. 编译期注解处理器:如 lombok。它仅在 javac 编译阶段修改抽象语法树生成 getter/setter 等字节码,编译完成后运行期不再需要该 JAR 存在。

runtime ​

runtime 表示该依赖在编译 Classpath 中不可见,仅在测试与运行 Classpath 中生效,会被打入最终发布包,且具备传递性。

它常用于接口与实现解耦的 SPI(Service Provider Interface)架构场景:

  • 数据库驱动:主代码只针对 JDK 标准 java.sql.* 接口编程,具体驱动(如 mysql-connector-j)设为 runtime,从编译层面阻断业务代码直接硬编码引用厂商内部类,同时确保测试与部署运行时能够加载驱动。
  • 日志实现层:业务代码面向 slf4j-api(compile)编程,具体的日志落盘实现(如 logback-classic)设为 runtime,后续切换日志框架无需修改业务源码。

test ​

test 表示该依赖仅在测试 Classpath(测试编译与测试执行阶段)生效,对 src/main/java 主代码不可见,不会被打包进发布产物,也不具备传递性。

单元测试框架与断言 Mock 工具(如 junit-jupiter、mockito-core、spring-boot-starter-test)都应显式声明为 test。

system ​

system 在 Classpath 可见性与打包行为上与 provided 完全一致(编译与测试有效、不打包、不传递),但 Maven 不会从本地或远程仓库检索它,而是强依赖 <systemPath> 指定的本机磁盘路径。

xml
<!-- 1. 引用项目内本地 JAR(不推荐,仅用于说明语法) -->
<dependency>
  <groupId>com.vendor</groupId>
  <artifactId>legacy-sdk</artifactId>
  <version>1.0.0</version>

  <!-- 2. 必须同时声明 system 作用域与本地磁盘路径 -->
  <scope>system</scope>
  <systemPath>${project.basedir}/lib/legacy-sdk-1.0.0.jar</systemPath>
</dependency>

Maven 官方已明确不推荐使用 system 作用域,因为它绕过了仓库托管体系,极易导致跨机器构建路径失效,且在多模块传递与打包插件处理中存在诸多边界限制。对于未上架中央仓库的内部或商业 JAR,正确做法是使用 mvn install:install-file 安装至本地仓库,或使用 mvn deploy:deploy-file 推送至企业私服后按常规 compile 坐标引入。

import ​

import 是一种特殊的非类路径作用域,仅允许出现在 <dependencyManagement> 内部,且必须与 <type>pom</type> 搭配使用。它不引入任何物理 JAR,也不参与三类 Classpath 装配,唯一作用是将外部 BOM(Bill of Materials)POM 中声明的 <dependencyManagement> 版本清单合并到当前工程。

由于 <parent> 仅支持单继承,当项目既需要继承企业内部公共父 POM,又需要对齐 Spring Cloud、JUnit 或 Jackson 等外部生态的版本矩阵时,通过 import 引入多份 BOM 是标准解法。

作用域能力对比 ​

下表汇总了六种作用域在编译、测试、运行三套 Classpath、最终打包及向下传递中的行为差异:

作用域编译 Classpath测试 Classpath运行 Classpath是否打入发布包是否传递典型依赖
compile有效有效有效是是gson、spring-core
provided有效有效无效否否javax.servlet-api、lombok
runtime无效有效有效是是mysql-connector-j、logback-classic
test无效有效无效否否junit-jupiter、mockito-core
system有效有效无效否否本地非仓库遗留 JAR
import不适用不适用不适用不适用不适用外部 BOM 清单(仅限 <dependencyManagement>)

作用域传递推导 ​

当项目 A 直接依赖 B(第一直接依赖),而 B 又依赖 C(第二直接依赖)时,C 对 A 而言成为传递依赖。C 在 A 中的最终生效作用域并非固定不变,而是由 A → B 的作用域 与 B → C 的作用域 联合推导得出:

A → B \ B → Ccompileprovidedruntimetest
compilecompile不传递runtime不传递
providedprovided不传递provided不传递
runtimeruntime不传递runtime不传递
testtest不传递test不传递

上表可以归结为三条核心推导规律:

  1. 第二直接依赖拦截规则:当 B → C 为 provided 或 test 时,无论 A → B 是何种作用域,C 都不会被传递到 A。

  2. 第一直接依赖降级规则:当 B → C 为 compile 时,C 传递给 A 后的生效作用域与 A → B 保持一致(例如 A 以 test 引入 B,B 的 compile 依赖进入 A 后也降级为 test)。

  3. 运行期收敛规则:当 B → C 为 runtime 时,若 A → B 为 compile,C 在 A 中保持 runtime;其余情形均收敛为 A → B 的作用域。

常见作用域误用问题 ​

在工程实践中,作用域配置不当往往不会在本地立即暴露,而是在打包部署或跨环境迁移时引发故障:

  1. Servlet API 误配 compile 引发容器冲突:若未将 javax.servlet-api 设为 provided,打包生成的 WAR 会将其收入 WEB-INF/lib。部署至 Tomcat 后,应用内的 Servlet 接口与容器自带的 servlet-api.jar 发生双份加载,轻则触发 Tomcat 警告丢弃 JAR,重则引发 LinkageError 或 ClassCastException。

  2. 在 runtime 作用域下硬编码实现类:将 mysql-connector-j 设为 runtime 后,若业务代码仍显式 import com.mysql.cj.jdbc.Driver 或调用厂商专有方法,编译阶段会直接报程序包不存在。此时应通过 DriverManager 或数据源配置字符串解耦,而非草率改回 compile。

  3. 测试工具漏配 test 导致产物膨胀与漏洞暴露:遗漏 <scope>test</scope> 会使 JUnit、Mockito 等测试依赖按默认 compile 进入生产包,不仅增大镜像与发布包体积,还会让安全扫描工具报出多余依赖的 CVE 风险。

  4. **本地绝对路径滥用 system**:使用如 C:/libs/foo.jar的<systemPath>会导致其他操作系统或 CI 流水线编译直接失败;且 Spring Boot 打包插件默认不收录system依赖,运行期容易抛出NoClassDefFoundError。

示例: Web 工程作用域配置 ​

下面以一个标准 Java Web 工程的依赖声明为例,综合展示 import、compile、provided、runtime 与 test 五种常用作用域的协同配置:

xml
<!-- 1. 在 dependencyManagement 中使用 import 导入 BOM 清单 -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- 2. compile(默认):编译、测试、运行全程有效,并打入最终 WAR 包 -->
  <dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.11.0</version>
  </dependency>

  <!-- 3. provided:仅编译与测试有效,运行期由 Tomcat 容器提供,不打包 -->
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>
  </dependency>

  <!-- 4. runtime:编译期不可见(强制面向 JDBC 接口编程),测试与运行期打包生效 -->
  <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.0.33</version>
    <scope>runtime</scope>
  </dependency>

  <!-- 5. test:仅在测试编译与测试执行阶段生效,不参与主代码编译与打包 -->
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

配置完成后,可通过 Maven 依赖插件命令直观核对各依赖的最终生效作用域以及不同阶段 Classpath 的实际成员:

bash
# 1. 查看各依赖及其生效的作用域标签
mvn dependency:tree

# 2. 分别导出编译期与运行期 Classpath,验证 provided 与 runtime 的隔离效果
mvn dependency:build-classpath -DincludeScope=compile
mvn dependency:build-classpath -DincludeScope=runtime

在 -DincludeScope=compile 输出中可以看到 gson 与 javax.servlet-api,而看不到 mysql-connector-j 与 junit-jupiter;在 -DincludeScope=runtime 输出中可以看到 gson 与 mysql-connector-j,而 javax.servlet-api 与 junit-jupiter 已被自动剥离。

传递依赖仲裁 ​

在 Maven 工程中,项目在 pom.xml 中显式声明的依赖称为直接依赖,而直接依赖自身的 .pom 文件所声明的下游依赖称为传递依赖。当多条依赖链路汇聚到同一个构件坐标(groupId 与 artifactId 相同)但版本号不同时,Java 单一类加载器环境下无法同时安全加载同一构件的多个版本,Maven 依赖解析器(Maven Resolver)必须通过确定性的依赖仲裁(Dependency Mediation)算法从中裁定唯一生效的版本,并丢弃其余冲突版本。

依赖冲突成因 ​

随着项目引入的框架与二方 SDK 增多,依赖关系会从简单的线性列表演变为有向无环图(DAG),进而产生典型的菱形依赖冲突:

  1. 多路径版本分歧:项目同时引入组件 A 与组件 B,A 内部依赖底层库 X 的 1.0 版本,而 B 内部依赖 X 的 2.0 版本。

  2. 低版本覆盖高版本风险:Maven 默认并非采用“高版本优先”策略。当旧版本 X(1.0)在仲裁中胜出、新版本 X(2.0)被裁减时,编译阶段可能完全正常,但在运行期一旦组件 B 调用了 2.0 才新增的类或方法,JVM 会直接抛出 NoSuchMethodError、NoClassDefFoundError、AbstractMethodError 或 IncompatibleClassChangeError。

  3. 同包不同坐标的隐蔽冲突:如果同一开源库在演进过程中更换了 groupId 或 artifactId(例如 log4j:log4j 与 org.apache.logging.log4j:log4j-core,或旧版 javax.* 与新版 jakarta.*),Maven 会将其视为两个完全独立的构件,不会触发版本仲裁,而是同时打入 Classpath,造成运行期类加载行为不确定。

image-20261120105155736

仲裁规则 ​

Maven Resolver 在展开依赖图时采用广度优先遍历(BFS),当遇到相同 groupId:artifactId 的多个候选版本时,严格按以下三级优先级执行裁定。

路径最近者优先 ​

路径最近者优先(Nearest Definition Wins)是 Maven 最核心的仲裁原则:在依赖树中,距离当前项目根节点路径跳数(深度)更短的版本胜出,与版本号高低无关。

假设当前项目 P 存在两条引入构件 X 的路径:

  • 路径一:P → A → B → X(3.0)(路径长度为 3)
  • 路径二:P → C → X(1.5)(路径长度为 2)

尽管 3.0 版本高于 1.5,但由于路径二仅有 2 跳、离项目更近,Maven 最终裁定 X(1.5) 生效并丢弃 X(3.0)。这也意味着,只要在当前项目的 <dependencies> 中直接显式声明某依赖(路径长度为 1),它必然优先于所有传递依赖。

第一声明者优先 ​

当多条路径到达同一构件的路径长度完全相等时,触发第一声明者优先(First Declaration Wins)规则:谁的根节点在当前 pom.xml 的 <dependencies> 中声明位置靠前,谁所携带的版本就胜出。

假设当前项目 P 中先声明 A、后声明 B:

  • 路径一:P → A → X(1.0)(路径长度为 2,A 声明在第 1 位)
  • 路径二:P → B → X(2.0)(路径长度为 2,B 声明在第 2 位)

此时 X(1.0) 胜出。如果开发者仅调整 pom.xml 中 A 与 B 的上下书写顺序,将 B 移至 A 之前,仲裁结果就会瞬间反转为 X(2.0)。因此,依赖声明顺序在等长冲突场景下直接影响运行期行为,工程上不应依赖隐式排序来碰运气。

dependencyManagement 覆盖 ​

在当前工程的 <dependencyManagement>(含父 POM 继承及 import 导入的 BOM 清单)中声明的版本号,对所有传递依赖具备最高锁定优先级:

  1. 直接覆写传递版本:只要某个传递依赖的 groupId:artifactId 命中了 <dependencyManagement> 条目,Maven 会直接将该传递依赖的版本强制替换为受管版本,不再受路径远近或声明先后影响。

  2. 不引入额外物理依赖:如果项目依赖树中原本没有任何路径引入该构件,写在 <dependencyManagement> 中的声明不会凭空触发下载或进入 Classpath。

  3. 与直接依赖的边界:若当前 <dependencies> 中已经对某直接依赖硬编码了 <version>,则以该直接依赖显式指定的版本为准。

依赖阻断 ​

除了被动等待仲裁或统一锁定版本外,Maven 提供了分别作用于供给方与消费方的两种阻断手段,用于主动切断不必要的传递链路。

optional ​

<optional>true</optional> 配置在组件供给方的 pom.xml 中,表示该依赖仅在供给方自身编译或特定分支下需要,不会自动传递给引用它的下游项目。

例如,一个通用持久层框架同时内置了对 MySQL 与 PostgreSQL 的适配代码,其自身编译时需要同时引入两款数据库驱动;但下游业务系统通常只使用其中一种数据库。供给方将两款驱动标记为 <optional>true</optional> 后,下游工程便不会被强制塞入多余驱动,只需按需显式声明自己使用的那一款即可。

xml
<!-- 1. 在基础组件 pom.xml 中声明可选依赖 -->
<dependency>
  <groupId>com.mysql</groupId>
  <artifactId>mysql-connector-j</artifactId>
  <version>8.0.33</version>

  <!-- 2. 设为 true 后,依赖当前组件的下游工程不会自动继承该驱动 -->
  <optional>true</optional>
</dependency>

exclusions ​

<exclusions> 配置在项目消费方的 pom.xml 中,用于在引入某个直接依赖时,精确剪除其携带的特定传递依赖(及其下游子依赖)。

该方式常用于两类场景:一是上游组件引入了过时、存在安全漏洞或冲突的第三方库(如旧版日志桥接包 slf4j-reload4j、commons-logging);二是替换底层默认实现(例如排除 Spring Boot 默认的 spring-boot-starter-tomcat 并换用 Undertow)。

xml
<!-- 1. 在消费方 pom.xml 中排除冲突的传递依赖 -->
<dependency>
  <groupId>org.apache.hadoop</groupId>
  <artifactId>hadoop-common</artifactId>
  <version>3.3.6</version>

  <!-- 2. 仅需指定 groupId 与 artifactId,严禁填写 version -->
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-reload4j</artifactId>
    </exclusion>
  </exclusions>
</dependency>

在 Maven 3.2.1 及以上版本中,<exclusion> 还支持通配符语法(将 <groupId> 与 <artifactId> 均设为 *),用于一次性阻断某个依赖的全部传递链;但这种粗粒度排除容易误伤必需的底层依赖,仅建议在明确自行接管全部运行时依赖的特殊场景下谨慎使用。

冲突诊断 ​

排查依赖冲突的核心工具是 maven-dependency-plugin。默认执行 mvn dependency:tree 只会输出仲裁后最终保留的精简树,被裁减的冲突节点会被隐藏;排查问题时必须附加 -Dverbose 参数展示完整仲裁明细。

bash
# 1. 打印包含被裁减节点的完整依赖树(默认模式会隐藏冲突节点)
mvn dependency:tree -Dverbose

# 2. 按坐标过滤特定依赖的所有引入路径与仲裁结果
mvn dependency:tree -Dverbose -Dincludes=com.google.guava:guava

# 3. 检查存在未声明却直接使用、或已声明却未使用的依赖
mvn dependency:analyze

在 -Dverbose 的树形输出中,被裁减的节点会用圆括号包裹并附带原因标注,主要分为以下三类:

输出标注含义说明
omitted for duplicate同一版本已在更近或更靠前的路径中引入,当前重复节点被去重省略,无版本冲突风险
omitted for conflict with <ver>当前版本因路径更远或声明更靠后而被裁减,最终生效的是 <ver>,属于重点排查的冲突信号
version managed from <old>当前节点的原始版本已被 <dependencyManagement> 强制改写为受管版本

实战: 依赖冲突排查与修复 ​

假设业务工程 order-app 同时引入了两个内部 SDK:sdk-alpha:1.2.0 与 sdk-beta:2.4.0。上线后调用 sdk-beta 的新接口时抛出 NoSuchMethodError,怀疑底层 guava 发生版本冲突。

定位冲突链路 ​

在工程根目录执行带过滤条件的详细依赖树命令,聚焦 guava 的所有引入路径:

bash
# 1. 仅展开包含 guava 的路径并显示被仲裁裁减的节点
mvn dependency:tree -Dverbose -Dincludes=com.google.guava:guava

控制台输出如下:

text
com.example:order-app:jar:1.0.0
+- com.example:sdk-alpha:jar:1.2.0:compile
|  \- com.google.guava:guava:jar:30.1-jre:compile
\- com.example:sdk-beta:jar:2.4.0:compile
   \- (com.google.guava:guava:jar:33.2.1-jre:compile - omitted for conflict with 30.1-jre)

从输出可以迅速还原根因:两条路径深度均为 2,但由于 sdk-alpha 在 pom.xml 中声明靠前,依据第一声明者优先规则,低版本 guava:30.1-jre 胜出,而 sdk-beta 依赖的高版本 33.2.1-jre 被裁减(omitted for conflict with 30.1-jre),直接触发运行期方法缺失异常。

统一锁定版本 ​

相比在 sdk-alpha 下逐一编写 <exclusions>,更规范且利于长期维护的做法是在 <dependencyManagement> 中显式锁定高版本 guava,让全工程所有传递路径自动收敛至兼容版本:

xml
<!-- 1. 通过 dependencyManagement 统一锁定传递依赖版本 -->
<dependencyManagement>
  <dependencies>
    <!-- 2. 强制将全局解析到的 guava 统一收敛至高版本 -->
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.2.1-jre</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 3. 业务直接依赖保持原样,无需逐个编写繁琐的 exclusions -->
<dependencies>
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>sdk-alpha</artifactId>
    <version>1.2.0</version>
  </dependency>

  <dependency>
    <groupId>com.example</groupId>
    <artifactId>sdk-beta</artifactId>
    <version>2.4.0</version>
  </dependency>
</dependencies>

修改完成后再次执行 mvn dependency:tree -Dverbose -Dincludes=com.google.guava:guava,可以看到 sdk-alpha 下的节点变为 33.2.1-jre (version managed from 30.1-jre),sdk-beta 下的节点变为 omitted for duplicate,冲突彻底消除。

构建期自动防线 ​

为了避免后续迭代引入新依赖时再次出现“低版本悄无声息覆盖高版本”的线上事故,可以在 pom.xml 中配置 maven-enforcer-plugin 并启用 requireUpperBoundDeps 规则。只要依赖树中最终胜出的版本低于任意分支声明的版本,构建就会在 validate 阶段直接失败并打印冲突路径。

xml
<!-- 1. 引入 enforcer 插件,在校验阶段自动拦截低版本覆盖高版本的风险 -->
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-enforcer-plugin</artifactId>
      <version>3.5.0</version>

      <!-- 2. 绑定 enforce 目标并启用上界版本检查规则 -->
      <executions>
        <execution>
          <id>enforce-upper-bound</id>
          <goals>
            <!-- 3. 若最终仲裁版本低于依赖树中的任意声明版本,则直接中止构建 -->
            <goal>enforce</goal>
          </goals>
          <configuration>
            <rules>
              <requireUpperBoundDeps/>
            </rules>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

如果团队对版本一致性要求更严苛,还可以启用 dependencyConvergence 规则,要求依赖树中同一构件的所有路径必须完全收敛至同一个版本号,否则强制报错,将隐患前置消灭在持续集成流水线中。