老程序员博客

编程生涯的最后一舞

当前位置：首页 > 技术 > 正文内容

Maven项目构建与依赖管理完全指南

访客 技术 2026年5月25日 3

一、Maven概述

1.1 为什么需要Maven

在Java项目开发中，第三方库的引入是不可避免的。然而，传统的手动管理方式存在诸多痛点：

jar包数量庞大：以Spring框架为例，一个完整的Spring项目可能需要引入百余个jar包，人工下载和整理的工作量巨大。

来源不稳定：部分第三方库的官方网站可能无法访问，或者下载的版本存在问题，导致项目运行时出现各种异常。

依赖关系复杂：jar包之间存在传递依赖，版本冲突问题难以手动排查解决。

Maven作为Apache旗下的开源项目，专门用于解决上述问题。它能够通过坐标（坐标机制）自动从远程仓库下载依赖，并智能处理依赖间的版本兼容性问题。

1.2 核心功能

Maven主要提供两大核心能力：

依赖管理：通过声明式的坐标配置，自动完成依赖下载、版本控制和冲突调解。

项目构建：将源代码、配置文件等资源标准化地编译、打包成可部署的jar或war文件。

1.3 工作原理

Maven的工作流程涉及本地仓库、远程仓库（中央仓库或镜像）以及项目pom配置。当执行构建命令时，Maven首先查询本地仓库，若不存在则从远程仓库下载并缓存到本地。

二、Maven环境搭建

2.1 安装前提

Maven需要Java运行环境支撑。确保系统中已配置JAVA_HOME环境变量，并安装了JDK 1.7或更高版本。

2.2 目录结构

maven-home/
├── bin/                    # 执行脚本目录
├── boot/                   # 类加载器框架
├── conf/                   # 配置文件目录
├── lib/                    # Maven运行时依赖库
└── LICENSE、NOTICE、README.txt
  • bin目录包含mvn命令脚本
  • conf目录中的settings.xml是核心配置文件
  • lib目录包含Maven运行所需的Java类库

2.3 环境变量配置

Windows系统：

# 新建系统变量
MAVEN_HOME=D:\apache-maven-3.9.0
# 编辑Path变量，添加
%MAVEN_HOME%\bin

Linux/Mac系统：

# 在~/.bashrc或~/.zshrc中添加
export MAVEN_HOME=/usr/local/apache-maven-3.9.0
export PATH=$PATH:$MAVEN_HOME/bin

验证安装：

mvn -v
# 成功输出Maven版本信息即表示安装完成

2.4 核心配置

编辑conf/settings.xml文件，主要配置项如下：

本地仓库路径：

<localRepository>/opt/maven/repository</localRepository>

镜像加速（推荐阿里云）：

<mirrors>
    <mirror>
        <id>aliyun-maven</id>
        <mirrorOf>central</mirrorOf>
        <name>Aliyun Maven Mirror</name>
        <url>https://maven.aliyun.com/repository/central</url>
    </mirror>
</mirrors>

JDK版本配置：

<profiles>
    <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>

2.5 IDE集成配置

以IntelliJ IDEA为例，配置步骤如下：

  1. 打开Settings → Build, Execution, Deployment → Build Tools → Maven
  2. 修改Maven home path为本地安装目录
  3. 指定User settings file为修改后的settings.xml
  4. 确保Local repository路径正确

三、Maven项目结构

3.1 GAV坐标体系

Maven通过GAV（GroupId、ArtifactId、Version、Packaging）四个维度唯一标识一个项目：

GroupId：组织标识，通常采用反向域名格式

  • 格式：com.{公司名}.{业务线}.{子模块}
  • 示例：com.alibaba.taobao.order

ArtifactId：项目或模块名称

  • 格式：产品线-模块名
  • 示例：trade-service、user-api

Version：版本号

  • 格式：主版本.次版本.修订号
  • 规范：
  • 主版本：重大架构变更时递增
  • 次版本：新增功能但保持向后兼容时递增
  • 修订号：修复bug时递增
  • 特殊版本：SNAPSHOT表示快照版，RELEASE表示正式版

Packaging：打包方式

  • jar：Java普通项目（默认值）
  • war：Web应用项目
  • pom：父项目或聚合项目

3.2 标准项目结构

project-root/
├── pom.xml                      # 项目对象模型配置文件
├── src/
│   ├── main/
│   │   ├── java/                # Java源代码
│   │   │   └── com/company/
│   │   │       └── app/
│   │   │           ├── controller/
│   │   │           ├── service/
│   │   │           ├── dao/
│   │   │           └── model/
│   │   ├── resources/           # 配置资源文件
│   │   │   ├── application.yml
│   │   │   └── mapper/
│   │   └── webapp/              # Web应用资源（war项目）
│   │       ├── WEB-INF/
│   │       │   └── web.xml
│   │       └── index.jsp
│   └── test/
│       ├── java/                # 测试代码
│       └── resources/           # 测试资源
└── target/                      # 编译输出目录

3.3 创建项目示例

创建Java SE项目：

mvn archetype:generate -DgroupId=com.example -DartifactId=demo-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

创建Java Web项目：

mvn archetype:generate -DgroupId=com.example -DartifactId=web-project -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

四、项目构建

4.1 构建命令

命令 功能说明
mvn compile 编译源代码
mvn test 执行单元测试
mvn package 打包成jar/war
mvn clean 清理target目录
mvn install 安装到本地仓库
mvn deploy 部署到远程仓库
mvn site 生成项目站点

常用组合命令：

# 清理并打包
mvn clean package
# 清理并安装
mvn clean install
# 跳过测试打包
mvn clean package -DskipTests

4.2 构建生命周期

Maven构建分为三套生命周期：

  1. clean生命周期：pre-clean → clean → post-clean
  2. default生命周期：compile → test → package → install → deploy
  3. site生命周期：site → site-deploy

每个生命周期包含多个阶段（phase），执行某个阶段时，该阶段之前的所有阶段会自动执行。

4.3 构建配置

在pom.xml的build节点配置：

自定义打包名称：

<build>
    <finalName>${project.artifactId}-${project.version}</finalName>
</build>

包含Java资源文件：

<build>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include>
                <include>**/*.properties</include>
            </includes>
        </resource>
    </resources>
</build>

常用插件配置：

<build>
    <plugins>
        <!-- 编译插件 -->
        <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>
            </configuration>
        </plugin>
        <!-- War打包插件 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>3.3.2</version>
        </plugin>
        <!-- Tomcat运行插件 -->
        <plugin>
            <groupId>org.apache.tomcat.maven</groupId>
            <artifactId>tomcat7-maven-plugin</artifactId>
            <version>2.2</version>
            <configuration>
                <port>8080</port>
                <path>/</path>
            </configuration>
        </plugin>
    </plugins>
</build>

五、依赖管理

5.1 依赖声明

在pom.xml的dependencies节点添加依赖：

<dependencies>
    <!-- Spring框架 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>6.0.11</version>
    </dependency>
    <!-- 日志框架 -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.7</version>
    </dependency>
    <!-- 测试框架 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

5.2 版本管理

使用properties节点统一管理版本号：

<properties>
    <spring.version>6.0.11</spring.version>
    <mybatis.version>3.5.14</mybatis.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>${spring.version}</version>
    </dependency>
</dependencies>

5.3 依赖范围

通过scope指定依赖的使用范围：

作用域 说明 示例
compile 编译、测试、运行均有效（默认） spring-core
test 仅测试阶段有效 junit
provided 编译、测试有效，运行时不参与 servlet-api
runtime 测试、运行有效，编译时不参与 jdbc-driver
system 本地系统依赖，需指定路径 -
import 导入依赖管理配置 -

5.4 依赖传递

Maven自动解析传递依赖：A依赖B，B依赖C，则A自动获得C的依赖。

依赖传递规则：

  • B依赖C使用compile范围：传递生效
  • B依赖C使用test或provided范围：传递终止
  • B依赖C配置optional=true：传递终止

终止传递配置：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid</artifactId>
    <version>1.2.18</version>
    <optional>true</optional>
</dependency>

5.5 依赖冲突解决

自动解决原则：

  1. 短路优先：路径短的版本优先
  • A→B→C→X(1.0)
  • A→D→X(2.0)
  • 优先选择X(2.0)
  1. 先声明优先：路径长度相同时，先声明的优先
  • A→E→X(1.0)
  • A→F→X(2.0)
  • 取决于E和F的声明顺序

手动排除：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>module-a</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

5.6 依赖下载失败处理

常见原因及解决方案：

  1. 网络问题：检查网络连接，确认镜像仓库可用
  2. 版本错误：核实依赖坐标信息正确性
  3. 缓存污染：删除本地仓库中的.lastUpdated文件后重新下载
# 清理本地仓库缓存
find ~/.m2/repository -name "*.lastUpdated" -delete
# 强制更新依赖
mvn clean install -U

六、继承与聚合

6.1 继承关系

通过继承机制，子工程可以继承父工程的依赖管理配置。

父工程配置：

<project>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    
    <!-- 依赖版本统一管理 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-beans</artifactId>
                <version>6.0.11</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

子工程配置：

<project>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>parent-project</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>child-module</artifactId>
    
    <!-- 继承父工程版本，无需指定 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-beans</artifactId>
        </dependency>
    </dependencies>
</project>

6.2 聚合关系

聚合项目用于管理多个子模块，通过父项目统一构建。

聚合配置：

<project>
    <groupId>com.example</groupId>
    <artifactId>aggregator-project</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    
    <modules>
        <module>module-common</module>
        <module>module-user</module>
        <module>module-order</module>
    </modules>
</project>

七、私服仓库

7.1 概述

Maven私有仓库（Nexus）架设在内网环境中，作为外部仓库的代理，提供以下价值：

  • 节省外网带宽，减少重复下载
  • 加快构建速度，仓库位于局域网
  • 部署内部私有构件
  • 保障项目稳定性，不依赖外部网络
  • 减轻中央仓库压力

7.2 Nexus部署

下载与安装：

# 解压
tar -zxf nexus-3.60.0-01.tar.gz
# 启动
cd nexus-3.60.0-01/bin
./nexus start

访问地址：http://localhost:8081

仓库类型：

  • proxy：远程仓库代理
  • hosted：本地宿主仓库
  • group：仓库组合

常用仓库：

  • maven-central：中央仓库代理
  • maven-public：公共仓库组
  • maven-releases：正式版发布仓库
  • maven-snapshots：快照版仓库

7.3 客户端配置

settings.xml配置：

<mirrors>
    <mirror>
        <id>nexus-local</id>
        <mirrorOf>*</mirrorOf>
        <name>Local Nexus</name>
        <url>http://localhost:8081/repository/maven-public/</url>
    </mirror>
</mirrors>

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

项目部署配置：

<distributionManagement>
    <repository>
        <id>nexus-local</id>
        <url>http://localhost:8081/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
        <id>nexus-local</id>
        <url>http://localhost:8081/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

执行部署：

mvn deploy

八、实战案例

8.1 项目架构

构建一个分布式电商系统，包含用户模块、订单模块和通用工具模块。

项目结构：

ecommerce-parent/
├── pom.xml
├── common-util/          # 通用工具模块
├── user-service/         # 用户服务
└── order-service/        # 订单服务

8.2 父项目配置

<?xml version="1.0" encoding="UTF-8"?>
<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>

    <groupId>com.ecommerce</groupId>
    <artifactId>ecommerce-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>common-util</module>
        <module>user-service</module>
        <module>order-service</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <spring.version>6.0.11</spring.version>
        <commons.version>2.14.0</commons.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-context</artifactId>
                <version>${spring.version}</version>
            </dependency>
            <dependency>
                <groupId>commons-codec</groupId>
                <artifactId>commons-codec</artifactId>
                <version>${commons.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

8.3 通用模块

<project>
    <parent>
        <artifactId>ecommerce-parent</artifactId>
        <groupId>com.ecommerce</groupId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>common-util</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
        <dependency>
            <groupId>commons-codec</groupId>
            <artifactId>commons-codec</artifactId>
        </dependency>
    </dependencies>
</project>

8.4 服务模块

用户服务：

<project>
    <parent>
        <artifactId>ecommerce-parent</artifactId>
        <groupId>com.ecommerce</groupId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>user-service</artifactId>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>com.ecommerce</groupId>
            <artifactId>common-util</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
            <version>6.0.11</version>
        </dependency>
    </dependencies>
</project>

订单服务：

<project>
    <parent>
        <artifactId>ecommerce-parent</artifactId>
        <groupId>com.ecommerce</groupId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>order-service</artifactId>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>com.ecommerce</groupId>
            <artifactId>common-util</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
            <version>6.0.11</version>
        </dependency>
    </dependencies>
</project>

8.5 统一构建

在父项目目录执行构建命令，所有子模块将自动构建：

# 清理并安装所有模块到本地仓库
mvn clean install

# 构建特定模块
mvn clean install -pl user-service

# 构建指定模块及其依赖
mvn clean install -pl user-service -am
标签: mavenJavadependency-managementbuild-toolsproject-structure
返回列表

上一篇：CentOS 7 环境下手动部署 MySQL 8.0 完整指南

下一篇：FAT16文件系统读写测试程序设计与实现

相关文章

Linux crontab 详解

1) crontab 是什么cron 是 Linux 的定时任务守护进程；crontab 是用来编辑/查看“按时间周期执行命令”的表（cron table）。常见两类：用户 crontab：每个用户一份（crontab -e 编辑）系统级 crontab / cron.d：可指定执行用户（/etc/crontab、/etc/cron.d/*）2) crontab 时间...

富文本里可以允许的 HTML 属性

一、所有标签默认允许的安全属性（极少）class        （可选）id           （通常建议禁用）title️ 注意：id 容易被滥用做锚点注入，很多系统直接禁用class 允许的话最好只允许固定前缀（如 editor-*）二、a 标签允许属性<a href="" t...

Mac 安装 Node.js 指南

方法一：通过官网安装包（最简单，适合初学者）如果你只是想快速安装并开始使用，这是最直接的方法。访问 Node.js 官网。页面会显示两个版本：LTS (Recommended For Most Users)：长期支持版，最稳定。建议选这个。Current：最新特性版，包含最新功能但可能不够稳定。下载 .pkg 安装包并运行。按照安装向导点击“下一步”即可完成。方法二：使用 Homebrew 安装（...

Dom\HTML_NO_DEFAULT_NS 的副作用：自动加闭合标签

在使用Dom\HTMLDocument时，Dom\HTML_NO_DEFAULT_NS 将禁止在解析过程中设置元素的命名空间, 此设置是为了与DOMDocument向后兼容而存在的。当使用它时，已知的一个副作用就是：自动加闭合标签例如 </img> 为什么会这样？当你使用：Dom\HTML_NO_DEFAULT_NS文档会变成 无命名空间模式，此时内部更接近 XML...

Laravel 事件和监听器创建

在 Laravel 中，使用 Artisan 命令创建 Events（事件） 和 Listeners（监听器） 是非常高效的。你可以通过以下几种方式来实现：1. 手动创建单个 Event如果你只想创建一个事件类，可以使用 make:event 命令：Bashphp artisan make:event UserRegistered执行后，文件将生成在 app/Even...

自定义域名解析神器 dnsmasq

什么是 dnsmasq？dnsmasq 是一个轻量级、功能强大的网络服务工具，专为小型和中等规模网络设计。它是一个综合的网络基础设施解决方案[1]。dnsmasq 能做什么？功能说明应用场景DNS 转发与缓存将 DNS 查询转发到上游服务器（ISP、Google DNS 等），并在本地缓存结果加快 DNS 查询速度，减少外部 DNS 流量本地 DNS解析本地网络设备的主机名，无需编辑&n...

发表评论

访客

◎欢迎参与讨论，请在这里发表您的看法和观点。

Copyright © agingcoder.cn

Powered By Z-BlogPHP. Theme by TOYEAN.