Maven 速查表

本文档整理了 Maven 最常用的命令、配置和技巧，方便快速查阅。

常用命令

项目构建

命令	说明
`mvn compile`	编译源代码
`mvn test`	运行单元测试
`mvn package`	打包项目（jar/war）
`mvn install`	安装到本地仓库
`mvn deploy`	部署到远程仓库
`mvn clean`	清理构建目录
`mvn clean package`	清理后重新打包

跳过测试

命令	说明
`mvn package -DskipTests`	跳过测试执行（仍编译测试代码）
`mvn package -Dmaven.test.skip=true`	完全跳过测试（不编译也不执行）

多模块项目

命令	说明
`mvn install -pl module-name`	只构建指定模块
`mvn install -pl module-name -am`	构建指定模块及其依赖模块
`mvn install -pl module-name -amd`	构建指定模块及依赖它的模块
`mvn install -rf :module-name`	从指定模块开始构建

依赖管理

命令	说明
`mvn dependency:tree`	查看依赖树
`mvn dependency:tree -Dverbose`	查看完整依赖树（含冲突）
`mvn dependency:tree -Dincludes=groupId:artifactId`	查看特定依赖的来源
`mvn dependency:analyze`	分析依赖使用情况
`mvn dependency:resolve`	解析所有依赖
`mvn dependency:purge-local-repository`	清除本地依赖缓存

项目信息

命令	说明
`mvn help:effective-pom`	查看有效 POM
`mvn help:active-profiles`	查看激活的 Profile
`mvn help:all-profiles`	查看所有 Profile
`mvn help:describe -Dplugin=compiler`	查看插件信息
`mvn versions:display-dependency-updates`	检查依赖更新
`mvn versions:display-plugin-updates`	检查插件更新

其他命令

命令	说明
`mvn archetype:generate`	从模板创建项目
`mvn site`	生成项目站点
`mvn validate`	验证项目正确性
`mvn -v` 或 `mvn --version`	显示版本信息
`mvn -o`	离线模式
`mvn -U`	强制更新快照依赖
`mvn -X`	显示调试信息
`mvn -e`	显示错误信息

POM 核心元素

项目坐标

<groupId>com.example</groupId>      <!-- 组织/公司标识 -->
<artifactId>my-project</artifactId> <!-- 项目名称 -->
<version>1.0.0</version>            <!-- 版本号 -->
<packaging>jar</packaging>          <!-- 打包类型：jar/war/pom/ear -->

依赖声明

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>5.3.23</version>
    <scope>compile</scope>          <!-- 依赖范围 -->
    <optional>false</optional>      <!-- 是否可选 -->
    <exclusions>                    <!-- 排除传递依赖 -->
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

依赖范围

Scope	编译	测试	运行	打包	传递
compile（默认）	✓	✓	✓	✓	✓
provided	✓	✓	✗	✗	✗
runtime	✗	✓	✓	✓	✓
test	✗	✓	✗	✗	✗
system	✓	✓	✓	✓	✗

依赖管理

<!-- 父 POM：只管理版本，不引入依赖 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>2.7.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 子模块：无需指定版本 -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <!-- 版本由父 POM 管理 -->
    </dependency>
</dependencies>

属性定义

<properties>
    <!-- 自定义属性 -->
    <spring.version>5.3.23</spring.version>
    <java.version>17</java.version>
    
    <!-- 内置属性使用 -->
    <!-- ${project.version} - 项目版本 -->
    <!-- ${project.basedir} - 项目根目录 -->
    <!-- ${project.build.directory} - 构建目录（target） -->
    <!-- ${env.JAVA_HOME} - 环境变量 -->
</properties>

构建生命周期

三套生命周期

Clean Lifecycle:     pre-clean → clean → post-clean
Default Lifecycle:   validate → compile → test → package → verify → install → deploy
Site Lifecycle:      pre-site → site → post-site → site-deploy

Default 生命周期主要阶段

阶段	说明
validate	验证项目正确性
compile	编译源代码
test	运行单元测试
package	打包（jar/war）
verify	验证包有效性
install	安装到本地仓库
deploy	部署到远程仓库

阶段执行规则

执行某个阶段时，会自动执行该阶段之前的所有阶段。例如 mvn package 会依次执行 validate → compile → test → package。

常用插件配置

编译插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <source>17</source>
        <target>17</target>
        <encoding>UTF-8</encoding>
        <compilerArgs>
            <arg>-parameters</arg>
        </compilerArgs>
    </configuration>
</plugin>

测试插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <skipTests>false</skipTests>
        <parallel>methods</parallel>
        <threadCount>4</threadCount>
    </configuration>
</plugin>

打包插件

<!-- 源码包 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.2.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>jar-no-fork</goal></goals>
        </execution>
    </executions>
</plugin>

<!-- 可执行 JAR（含依赖） -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.example.Main</mainClass>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

Profile 配置

多环境配置

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <env>development</env>
            <db.url>jdbc:mysql://localhost:3306/dev_db</db.url>
        </properties>
    </profile>
    
    <profile>
        <id>prod</id>
        <properties>
            <env>production</env>
            <db.url>jdbc:mysql://prod-server:3306/prod_db</db.url>
        </properties>
    </profile>
</profiles>

激活 Profile

mvn package -Pdev          # 命令行激活
mvn package -Pdev,test     # 激活多个
mvn package -Denv=prod     # 通过属性激活

settings.xml 配置

文件位置

全局配置：${maven.home}/conf/settings.xml
用户配置：${user.home}/.m2/settings.xml

镜像配置

<mirrors>
    <mirror>
        <id>aliyun</id>
        <mirrorOf>central</mirrorOf>
        <name>阿里云镜像</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

服务器认证

<servers>
    <server>
        <id>nexus-releases</id>
        <username>admin</username>
        <password>admin123</password>
    </server>
</servers>

本地仓库位置

<settings>
    <localRepository>D:/maven/repository</localRepository>
</settings>

多模块项目

父 POM

<project>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    
    <modules>
        <module>common</module>
        <module>service</module>
        <module>web</module>
    </modules>
    
    <dependencyManagement>
        <!-- 统一管理版本 -->
    </dependencyManagement>
</project>

子模块

<project>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>parent-project</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    
    <artifactId>common</artifactId>
</project>

版本号规范

版本格式

主版本.次版本.增量版本-里程碑版本
例如：1.0.0、1.2.3-SNAPSHOT、2.0.0-RC1

里程碑标识

标识	说明
SNAPSHOT	快照版（开发中）
ALPHA	内部测试版
BETA	公开测试版
RC	Release Candidate（候选发布版）
RELEASE	正式发布版
GA	General Availability（正式发布版）

版本范围

写法	说明
`1.0`	软性要求 1.0，可被其他版本替代
`[1.0]`	硬性要求 1.0，必须使用此版本
`[1.0,2.0)`	1.0 ≤ x < 2.0
`[1.0,)`	x ≥ 1.0
`(,1.0]`	x ≤ 1.0

常见问题排查

查看依赖冲突

# 查看依赖树
mvn dependency:tree -Dverbose

# 查找特定依赖
mvn dependency:tree -Dincludes=groupId:artifactId

# 分析依赖
mvn dependency:analyze

强制更新依赖

mvn clean install -U

查看有效配置

mvn help:effective-pom
mvn help:effective-settings

编译问题排查

# 显示详细错误
mvn compile -e

# 显示调试信息
mvn compile -X

项目标准目录结构

my-project/
├── pom.xml                      # 项目配置文件
├── src/
│   ├── main/
│   │   ├── java/                # 源代码
│   │   ├── resources/           # 资源文件
│   │   ├── filters/             # 资源过滤文件
│   │   └── webapp/              # Web 应用目录（WAR 项目）
│   └── test/
│       ├── java/                # 测试代码
│       └── resources/           # 测试资源
├── target/                      # 构建输出目录
└── .mvn/                        # Maven Wrapper 配置
    └── wrapper/
        └── maven-wrapper.properties

常用镜像源

镜像源	地址
阿里云	https://maven.aliyun.com/repository/public
华为云	https://repo.huaweicloud.com/repository/maven/
腾讯云	https://mirrors.cloud.tencent.com/nexus/repository/maven-public/

常用命令​

项目构建​

跳过测试​

多模块项目​

依赖管理​

项目信息​

其他命令​

POM 核心元素​

项目坐标​

依赖声明​

依赖范围​

依赖管理​

属性定义​

构建生命周期​

三套生命周期​

Default 生命周期主要阶段​

阶段执行规则​

常用插件配置​

编译插件​

测试插件​

打包插件​

Profile 配置​

多环境配置​

激活 Profile​

settings.xml 配置​

文件位置​

镜像配置​

服务器认证​

本地仓库位置​

多模块项目​

父 POM​

子模块​

版本号规范​

版本格式​

里程碑标识​

版本范围​

常见问题排查​

查看依赖冲突​

强制更新依赖​

查看有效配置​

编译问题排查​

项目标准目录结构​

常用镜像源​

常用命令

项目构建

跳过测试

多模块项目

依赖管理

项目信息

其他命令

POM 核心元素

项目坐标

依赖声明

依赖范围

依赖管理

属性定义

构建生命周期

三套生命周期

Default 生命周期主要阶段

阶段执行规则

常用插件配置

编译插件

测试插件

打包插件

Profile 配置

多环境配置

激活 Profile

settings.xml 配置

文件位置

镜像配置

服务器认证

本地仓库位置

多模块项目

父 POM

子模块

版本号规范

版本格式

里程碑标识

版本范围

常见问题排查

查看依赖冲突

强制更新依赖

查看有效配置

编译问题排查

项目标准目录结构

常用镜像源