Maven依赖作用域（Scope）详解

最新推荐文章于 2025-08-28 10:15:56 发布

原创最新推荐文章于 2025-08-28 10:15:56 发布 · 1.3k 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#maven #java

Maven依赖作用域（Scope）详解

核心概念

scope 属性用于定义依赖项在项目生命周期中的可用范围，即指定一个 JAR 包在何时、何处可以被使用。它决定了依赖是否会被包含在不同的 classpath 中，以及是否会被打包到最终的构建输出里，是 Maven 依赖管理的关键机制。

作用域对比总览

下表直观地展示了所有 scope 的区别：

作用域 (Scope)	编译 Classpath	测试 Classpath	运行时 Classpath	打包时包含	传递性	典型应用场景
`compile` (默认)	✅	✅	✅	✅	✅	项目核心依赖（如 Spring Framework, Lombok, Jackson）
`provided` (已提供)	✅	✅	❌	❌	❌	由运行环境提供的库（如 Servlet API, JSP API）
`runtime` (运行时)	❌	✅	✅	✅	✅	仅运行时需要的实现（如 MySQL JDBC 驱动）
`test` (测试)	❌	✅	❌	❌	❌	仅用于测试的框架（如 JUnit, Mockito, TestNG）
`system` (系统)	✅	✅	❌	❌	❌	(不推荐) 本地系统路径的 JAR 包
`import` (导入)	❌	❌	❌	❌	❌	(特殊) 仅用于继承依赖管理（如 Spring BOM）

各作用域详细说明

1. `compile`（编译范围）

行为描述：这是默认值。依赖在项目的所有阶段（编译主代码、编译测试代码、运行测试、运行时）都可用，并且会传递给依赖本项目的其他模块。
核心区别：所有阶段都可用，范围最广。
使用场景：你的项目业务代码直接依赖的、在运行时也必不可少的核心库。
典型例子：

- org.springframework.boot:spring-boot-starter-web
- org.projectlombok:lombok
- com.fasterxml.jackson.core:jackson-databind
- org.hibernate:hibernate-core

2. `provided`（已提供范围）

行为描述：表示该依赖在编译和测试阶段需要，但在运行时由 JDK、应用服务器（如 Tomcat, Jetty）或容器自动提供。因此，它不会被打包到最终的部署文件（如 WAR）中，也不具有传递性。
核心区别：与 compile 的关键区别在于运行时由环境提供，无需打包，避免了与环境自带库的冲突。
使用场景：那些由运行环境提供的库。
典型例子：

- jakarta.servlet:jakarta.servlet-api (这是您案例中的典型用法)
- jakarta.servlet.jsp:jakarta.servlet.jsp-api
- javax.annotation:javax.annotation-api (部分环境提供)

3. `runtime`（运行时范围）

行为描述：依赖在编译时不需要（你的代码不直接 import 它的类），但在测试和运行时需要。它会被打包到最终的输出中，并且具有传递性。
核心区别：与 compile 相反，编译时不需要但运行时需要。
使用场景：运行时才需要的具体实现，而编译期只依赖其接口。
典型例子：

- mysql:mysql-connector-java (编译期只依赖 java.sql 接口，运行时需要此驱动实现)
- com.h2database:h2 (常用于测试阶段的运行时数据库)
- 某些日志库的具体实现（如 logback-classic）

4. `test`（测试范围）

行为描述：依赖仅用于测试阶段（编译和运行测试代码），在主代码的编译和运行时都不需要。它不会被打包，也不具有传递性。
核心区别：范围被严格限定在测试相关环节。
使用场景：所有仅用于测试的库和框架。
典型例子：

- org.junit.jupiter:junit-jupiter
- org.mockito:mockito-core
- org.springframework.boot:spring-boot-starter-test

5. `system`（系统范围）

行为描述：与 provided 类似，但你需要通过 <systemPath> 元素显式地指定一个本地文件系统上的 jar 包绝对路径。它极度缺乏可移植性，因为其他机器上很可能没有相同路径的文件。
核心区别：行为类似 provided，但依赖的不是 Maven 仓库，而是本地绝对路径。强烈不推荐使用。
使用场景：应极力避免。仅在无法通过 Maven 仓库获取的、非常古老的遗留第三方 jar 包时作为临时解决方案。
配置示例：

<dependency>
    <groupId>com.legacy</groupId>
    <artifactId>some-old-library</artifactId>
    <version>1.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/some-old-library-1.0.jar</systemPath>
</dependency>

6. `import`（导入范围）

行为描述：这是一种特殊作用域，仅用于 <dependencyManagement> 部分中的 pom 类型依赖。它不是用来引入普通 JAR 包的，而是用来合并（导入）另一个 POM 文件中的 <dependencyManagement> 配置，从而实现依赖管理的继承和组合，有效统一多模块项目的依赖版本。
核心区别：它不实际引入代码依赖，只导入“依赖如何管理”的规则。
使用场景：管理大型项目或生态系统的依赖版本。
经典例子：导入 Spring Boot 的依赖管理 BOM (Bill of Materials)

<dependencyManagement>
    <dependencies>
        <!-- 导入Spring Boot预定义的所有依赖版本 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type> <!-- 注意：type 必须为 pom -->
            <scope>import</scope> <!-- 关键作用域 -->
        </dependency>
    </dependencies>
</dependencyManagement>

此后，你在声明 Spring Boot 生态内的依赖时就可以省略 <version> 标签，版本由 BOM 统一控制。