Maven入门教程 - 技术栈

一、Maven简介

Maven 是一个基于项目对象模型（Project Object Model）的构建工具，用于管理 Java 项目的依赖、构建流程和文档生成。它的核心功能包括：

依赖管理(Dependency Management)：自动下载和管理第三方库（JAR 文件）。
标准化项目结构：统一项目目录布局。
构建生命周期(Project Lifecycle)：提供编译、测试、打包、部署等标准化流程。
插件系统：支持扩展功能（如代码检查、生成报告）。

1. 依赖管理

① jar包的规模

② jar包的来源: 使用 Maven 之后，jar 包会从规范的远程仓库下载到本地

③ jar包之间的依赖关系: 通过依赖的传递性自动完成

2. 标准化项目结构

约定优于配置（Convention Over Configuration）

目录	说明
src/main/java	主代码目录
src/main/resources	资源文件目录
src/test/java	测试代码目录
src/test/resources	测试使用的资源文件目录
pom.xml	项目配置文件
target	输出目录

3. 构建生命周期

清理：删除上一次构建的结果，为下一次构建做好准备
编译：Java 源程序编译成 *.class 字节码文件
测试：运行提前准备好的测试程序
报告：针对刚才测试的结果生成一个全面的信息
打包
- Java工程：jar包
- Web工程：war包
安装：把一个 Maven 工程经过打包操作生成的 jar 包或 war 包存入 Maven 仓库
部署
- 部署 jar 包：把一个 jar 包部署到 Nexus 私服服务器上
- 部署 war 包：借助相关 Maven 插件（例如 cargo），将 war 包部署到 Tomcat 服务器上

4. 插件系统

Maven 的核心设计理念是"约定优于配置"，其功能实现高度依赖插件系统 。Maven 插件是扩展 Maven 功能的工具，每个插件包含一组 目标（Goals） ，用于执行特定任务（如编译代码、打包、部署等）。
核心特点：

生命周期绑定：插件目标（Goals）与 Maven 的生命周期阶段（Phase）绑定。
高度可扩展：支持自定义插件或使用第三方插件。
配置灵活：通过 POM 文件或命令行参数控制插件行为。

二、安装配置

1. 安装 Java

Maven 依赖 Java 环境，请先安装 JDK 8+ 并配置 JAVA_HOME。

2. 下载 Maven

官网下载地址：https://maven.apache.org/download.cgi
选择二进制包（如 apache-maven-3.x.x-bin.zip）。

3. 配置环境变量

M2_HOME
PATH：将Maven的bin目录添加到PATH环境变量

4. 配置(conf/settings.xml)

指定本地仓库

xml 复制代码

<!-- localRepository
| The path to the local repository maven will use to store artifacts.
|
| Default: ${user.home}/.m2/repository
<localRepository>/path/to/local/repo</localRepository>
-->
<localRepository>D:\maven-repo</localRepository>

配置阿里云提供的镜像仓库

xml 复制代码

<!-- 阿里云镜像 -->
<mirror>
  <id>aliyunmaven</id>
  <name>阿里云公共仓库</name>
  <url>https://maven.aliyun.com/repository/public</url>
  <!-- 匹配所有仓库请求 -->
  <mirrorOf>*</mirrorOf>
</mirror>

配置 Maven 工程的基础 JDK 版本

xml 复制代码

<profile>
    <id>jdk-1.8</id>
    <activation>
        <activeByDefault>true</activeByDefault>
        <jdk>1.8</jdk>
    </activation>
    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <maven.compiler.compilerVersion>1.8</maven.compiler.compilerVersion>
    </properties>
</profile>

5. IDEA集成Maven环境

配置Maven信息

三、Maven基本命令

1. 创建项目

shell 复制代码

mvn archetype:generate -DgroupId=com.example -DartifactId=my-first-app  -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

groupId: 组织标识（如公司域名倒写）。

artifactId: 项目名称（生成的项目目录名）。

archetypeArtifactId：指定项目模板。

生成的标准目录结构如下：

my-first-app/
├── src/
│   ├── main/
│   │   └── java/      # 主代码目录
│   └── test/
│       └── java/      # 测试代码目录
├── pom.xml            # 项目配置文件

2. 项目对象模型(POM)

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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-first-app</artifactId>
  
  <!-- 当前Maven工程的打包方式，可选值有下面三种： -->
  <!-- jar：表示这个工程是一个Java工程 -->
  <!-- war：表示这个工程是一个Web工程 -->
  <!-- pom：表示这个工程是"管理其他工程"的工程 -->
  <packaging>jar</packaging>
  
  <version>1.0-SNAPSHOT</version>
  <name>my-first-app</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

更详细的pom文件,可以运行下面的命令获取：

shell 复制代码

mvn help:effective-pom

3. 常用命令

命令	功能说明
`mvn clean`	清理 target 目录（删除编译结果）
`mvn compile`	编译主代码，主体程序编译结果存放的目录：target/classes
`mvn test-compile`	编译测试代码，测试程序编译结果存放的目录：target/test-classes
`mvn test`	运行测试代码，测试的报告存放的目录：target/surefire-reports
`mvn package`	打包项目（生成 JAR/WAR 文件），存放的目录：target
`mvn install`	将项目安装到本地仓库
`mvn deploy`	部署到远程仓库（需配置）
`mvn site`	生成项目报告网站

完整构建流程命令mvn clean package会依次执行 clean→compile→test→package`。

四、核心概念

1. 坐标

groupId：公司或组织的 id，公司或组织域名的倒序
artifactId：一个项目或者是项目中的一个模块的 id
version：版本号

例如：SNAPSHOT 表示快照版本，正在迭代过程中，不稳定的版本

例如：RELEASE 表示正式版本
scope：依赖的范围
- compile：默认的scope。任何定义在compile scope下的依赖将会在所有的class paths下可用。maven工程会将其打包到最终的artifact中。如果你构建一个WAR类型的artifact，那么在compile scope下引用的JAR文件将会被集成到WAR文件内。
- provided：这个scope假定对应的依赖会由运行这个应用的JDK或者容器来提供。最好的例子就是servlet API。任何在provided scope下定义的依赖在构建时的类路径里是可用的，但是不会被打包到最终的artifact中。如果是一个WAR的文件，servlet API在构建时的类路径里是可用的，但是并不会被打包到WAR文件中。
- runtime：在runtime scope下定义的依赖只会在运行期可用，而在构建期的类路径下不可用。这些依赖将会被打包到最终的artifact中。比如你有一个基于web的应用需要在运行时访问MySQL数据库。你的代码没有任何MySQL数据库驱动的硬依赖。你的代码仅仅是基于JDBC API来编写，在构建期并不需要MySQL数据库驱动。然而，在运行期，就需要相应的驱动来操作MySQL数据库了。因此，这个驱动应该被打包到最终的artifact中。
- test：只用于测试变异的依赖（比如JUnit），execution必须定义在test scope下。这些依赖不会被打包到最终的artifact中。
- system：于provided scope很像。唯一的区别在于，在system scope中，你需要告诉Maven如何去找到这个依赖。如果你要引用的依赖在Maven仓库中不存在时，就可以用这个scope。不推荐使用system依赖。
- import：从其它的pom文件中导入依赖设置

2. 生命周期

所谓lifecycle，可以理解为可以执行一组命令的集合，用来执行具体的某些操作。

Maven默认有三种lifecycle：default，clean和site。default主要用来处理项目的开发，clean主要用来负责项目的清理，site主要用来生成项目的文档。

lifecycle是由一个或者多个phase组成的。

以default为例，它大概由23个phases组成，这些phases将会按顺序执行来完成default的lifecycle

validate: 验证项目是否正确，以及所有为了完整构建必要的信息是否可用
generate-sources: 生成所有需要包含在编译过程中的源代码
process-sources: 处理源代码，比如过滤一些值
generate-resources: 生成所有需要包含在打包过程中的资源文件
process-resources: 复制并处理资源文件至目标目录，准备打包
compile: 编译项目的源代码
process-classes: 后处理编译生成的文件，例如对Java类进行字节码增强（bytecode enhancement）
generate-test-sources: 生成所有包含在测试编译过程中的测试源码
process-test-sources: 处理测试源码，比如过滤一些值
generate-test-resources: 生成测试需要的资源文件
process-test-resources: 复制并处理测试资源文件至测试目标目录
test-compile: 编译测试源码至测试目标目录
test:使用合适的单元测试框架运行测试。这些测试应该不需要代码被打包或发布
prepare-package: 在真正的打包之前，执行一些准备打包必要的操作。这通常会产生一个包的展开的处理过的版本（将会在Maven 2.1+中实现）
package: 将编译好的代码打包成可分发的格式，如JAR，WAR，或者EAR
pre-integration-test: 执行一些在集成测试运行之前需要的动作。如建立集成测试需要的环境
integration-test: 如果有必要的话，处理包并发布至集成测试可以运行的环境
post-integration-test: 执行一些在集成测试运行之后需要的动作。如清理集成测试环境。
verify: 执行所有检查，验证包是有效的，符合质量规范
install: 安装包至本地仓库，以备本地的其它项目作为依赖使用
deploy: 复制最终的包至远程仓库，共享给其它开发人员和项目（通常和一次正式的发布相关）

3. mvn package目标执行顺序

resources:resources
Resources插件的resources目标绑定到了resources 阶段。这个目标复制src/main/resources下的所有资源和其它任何配置的资源目录，到输出目录。
compiler:compile
Compiler插件的compile目标绑定到了compile 阶段。这个目标编译src/main/java下的所有源代码和其他任何配置的资源目录，到输出目录。
resources:testResources
Resources插件的testResources目标绑定到了test-resources 阶段。这个目标复制src/test/resources下的所有资源和其它任何的配置的测试资源目录，到测试输出目录。
compiler:testCompile
Compiler插件的testCompile目标绑定到了test-compile 阶段。这个目标编译src/test/java下的测试用例和其它任何的配置的测试资源目录，到测试输出目录。
surefire:test
Surefire插件的test目标绑定到了test 阶段。这个目标运行所有的测试并且创建那些捕捉详细测试结果的输出文件。默认情况下，如果有测试失败，这个目标会终止。
jar:jar
Jar插件的jar目标绑定到了package 阶段。这个目标把输出目录打包成JAR文件。

五、常见问题

1. 依赖下载失败

现象：执行 mvn install 时出现 Could not resolve dependencies 错误。

原因: 网络问题或仓库配置错误; 依赖版本不存在; 本地仓库缓存损坏

解决办法:

（1）检查仓库配置

确认 settings.xml 中镜像（如阿里云）配置正确（参考之前的配置方法）。

（2）清理本地仓库缓存

shell 复制代码

# 删除所有未下载完成的临时文件
mvn dependency:purge-local-repository
# 或手动删除本地仓库中的相关依赖目录（路径：~/.m2/repository/）

（3）手动下载依赖 *

访问仓库地址（如 Maven Central 或阿里云仓库），确认依赖是否存在。

2. 依赖冲突（版本冲突）

现象：运行时出现 NoSuchMethodError 或 ClassNotFoundException。

解决办法

（1）分析依赖树

shell 复制代码

mvn dependency:tree -Dincludes=groupId:artifactId

输出示例：

[INFO] com.example:project:jar:1.0  
[INFO] +- org.slf4j:slf4j-api:jar:1.7.30:compile  
[INFO] \- ch.qos.logback:logback-classic:jar:1.2.3:compile  
[INFO]    \- ch.qos.logback:logback-core:jar:1.2.3:compile

（2）排除冲突依赖

在 pom.xml 中排除特定传递依赖：

xml 复制代码

<dependency>
    <groupId>org.example</groupId>
    <artifactId>example-lib</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflict-group</groupId>
            <artifactId>conflict-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 插件执行失败

现象：提示 Plugin execution failed 或 No plugin found。

解决办法：

（1）更新插件版本

在 pom.xml 中显式指定插件版本：

xml 复制代码

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
        </plugin>
    </plugins>
</build>

（2）检查插件配置

确认插件的 <configuration> 参数是否正确（如 JDK 版本）。

4. 资源文件未生效

现象：src/main/resources 中的配置文件未被打包，或变量未替换。

解决办法

（1）启用资源过滤

在 pom.xml 中配置资源目录和过滤：

xml 复制代码

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>  <!-- 启用变量替换 -->
        </resource>
    </resources>
</build>

（2）检查文件路径

确保资源文件位于正确目录，未被 .gitignore 或 .mvnignore 排除。

5. 多模块项目问题

现象：父模块与子模块依赖不继承，或构建顺序错误。

解决办法

（1）正确声明父模块

子模块的 pom.xml 中需指定父模块：

xml 复制代码

<parent>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0</version>
    <relativePath>../pom.xml</relativePath>  <!-- 父模块路径 -->
</parent>

（2）统一管理依赖版本

在父模块的 <dependencyManagement> 中定义公共依赖版本。

6.本地仓库缓存问题

现象：依赖已更新，但本地构建仍使用旧版本。

解决办法

（1）清理本地仓库

mvn dependency:purge-local-repository

（2）强制更新 SNAPSHOT 版本

mvn clean install -U

7. 版本号问题（SNAPSHOT vs RELEASE）

现象：SNAPSHOT 版本未更新到最新。

解决办法

SNAPSHOT 版本 ：Maven 默认每天检查一次更新，可通过 -U 强制更新：
```
mvn clean install -U
```
RELEASE 版本：版本号固定，需手动升级。

8. 其他常见错误

错误提示	可能原因	解决方案
`Project build error: Non-resolvable parent POM`	父模块未正确声明或仓库中不存在	检查父模块的 `<relativePath>` 或手动安装父模块到本地仓库
`Invalid JDK version in project`	JDK 版本不匹配	在 `pom.xml` 中配置 `maven-compiler-plugin` 的 `<source>` 和 `<target>`
`Failed to read artifact descriptor`	依赖的 POM 文件损坏或缺失	删除本地仓库中的依赖目录，重新下载

9. 常用排查命令

shell 复制代码

# 查看依赖树
mvn dependency:tree

# 查看有效配置（合并所有配置后的最终结果）
mvn help:effective-pom

# 清理项目并重新构建
mvn clean install

# 跳过测试
mvn install -DskipTests

附、常用插件

1. 核心构建插件

maven-compiler-plugin
- 作用: 编译 Java 源代码。
- groupId : org.apache.maven.plugins
- artifactId : maven-compiler-plugin
- 常用配置：
  xml 复制代码
```
<configuration>
  <source>1.8</source>  
  <target>1.8</target>
  <encoding>UTF-8</encoding>
</configuration>
```
maven-clean-plugin
- 作用 : 清理构建输出目录（默认删除 target/）。
- 命令 : mvn clean

2. 测试与报告插件

maven-surefire-plugin
- 作用: 运行单元测试（JUnit、TestNG）。
- groupId : org.apache.maven.plugins
- 跳过测试：
  shell 复制代码
```
mvn test -DskipTests
```
maven-failsafe-plugin
- 作用 : 运行集成测试（通常绑定到 verify 阶段）。
- groupId : org.apache.maven.plugins
- 命令 : mvn verify
maven-javadoc-plugin
- 作用: 生成 Javadoc 文档。
- 常用命令：
  shell 复制代码
```
mvn javadoc:javadoc  # 生成文档到 target/site/apidocs
```

3. 打包与部署插件

maven-jar-plugin
- 作用: 打包项目为 JAR 文件。
- groupId : org.apache.maven.plugins
- 默认绑定阶段 : package
maven-war-plugin
- 作用: 打包 Web 项目为 WAR 文件。
- groupId : org.apache.maven.plugins
- 配置示例：
  xml 复制代码
```
<packaging>war</packaging>  
```
maven-assembly-plugin
- 作用: 定制化打包（如生成包含依赖的 ZIP/TAR 包）。
- groupId : org.apache.maven.plugins
- 常用命令：
  shell 复制代码
```
mvn assembly:single
```

maven-shade-plugin

作用: 打包可执行 Fat JAR（合并依赖）。
groupId : org.apache.maven.plugins

典型配置：

xml 复制代码

<configuration>
  <transformers>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
      <mainClass>com.example.Main</mainClass>  <!-- 指定主类 -->
    </transformer>
  </transformers>
</configuration>

maven-deploy-plugin
- 作用: 将构建产物部署到远程仓库（如 Nexus）。
- groupId : org.apache.maven.plugins
- 命令 : mvn deploy

4. 依赖管理插件

maven-dependency-plugin
- 作用: 分析、复制或解压依赖。
- groupId : org.apache.maven.plugins
- 常用命令：
  shell 复制代码
```
mvn dependency:tree          # 查看依赖树
mvn dependency:copy-dependencies -DoutputDirectory=libs  # 复制依赖到目录
```
versions-maven-plugin
- 作用: 管理依赖版本（检查更新、升级版本）。
- groupId : org.codehaus.mojo
- 常用命令：
  shell 复制代码
```
mvn versions:display-dependency-updates  # 检查依赖更新
mvn versions:set -DnewVersion=2.0.0      # 批量修改版本号
```

5. 代码质量与静态分析

maven-checkstyle-plugin
- 作用: 检查代码风格是否符合规范。
- groupId : org.apache.maven.plugins
- 绑定阶段 : validate
maven-pmd-plugin
- 作用: 静态代码分析（检测潜在 Bug、复杂代码）。
- groupId : org.apache.maven.plugins
jacoco-maven-plugin
- 作用: 生成单元测试覆盖率报告。
- groupId : org.jacoco
- 常用命令：
  shell 复制代码
```
mvn jacoco:report  # 生成报告到 target/site/jacoco
```

6. 容器化与云原生

spring-boot-maven-plugin
- 作用: 打包 Spring Boot 应用（可执行 JAR）。
- groupId : org.springframework.boot
- 配置示例：
  xml 复制代码
```
<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
```

docker-maven-plugin

作用: 构建 Docker 镜像并推送至仓库。
groupId : io.fabric8

典型配置：

<configuration>
  <images>
    <image>
      <name>my-app:${project.version}</name>
      <build>
        <dockerFile>Dockerfile</dockerFile>
      </build>
    </image>
  </images>
</configuration>

7. 其他实用插件

exec-maven-plugin
- 作用: 直接运行 Java 类或 Shell 命令。
- groupId : org.codehaus.mojo
- 运行 Main 类：
```
mvn exec:java -Dexec.mainClass="com.example.Main"
```

flatten-maven-plugin

作用: 简化 POM 文件（去除冗余信息，适合发布）。
groupId : org.codehaus.mojo

配置示例：

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>flatten-maven-plugin</artifactId>
  <version>1.3.0</version>
  <configuration>
    <flattenMode>oss</flattenMode>
  </configuration>
</plugin>

antrun-maven-plugin

作用: 在 Maven 中执行 Ant 任务。
groupId : org.apache.maven.plugins

示例：

<execution>
  <id>copy-files</id>
  <phase>package</phase>
  <goals><goal>run</goal></goals>
  <configuration>
    <target>
      <copy file="src/data/config.xml" toFile="target/config.xml"/>
    </target>
  </configuration>
</execution>

使用建议：

（1）官方插件优先在 Maven Plugins List 查找。

（2）第三方插件可在 Maven Central 搜索。

（3）通过 mvn help:describe -Dplugin=插件ID 查看插件详情。