02-Maven-第 2 章 [实践] 环境配置与项目创建

Maven-第 2 章 [实践] 环境配置与项目创建

摘要: 理论是基础，但实践才能出真知。在理解了 Maven 的核心价值后，本章将是我们的第一个动手实践环节。我们将一步步地在自己的电脑上完成 Maven 环境的搭建 与 IDE 的集成，并最终亲手创建第一个可以运行的 Maven 项目。本章的目标是“立竿见影”，让您在最短时间内获得使用 Maven 的真实体验和成就感。

2.1. Maven 的安装与 settings.xml 核心配置

[在开始之前，请确保您的电脑已经正确安装了 JDK 并配置好了 JAVA_HOME 环境变量，这是 Maven 运行的唯一前置条件。]

2.1.1. Maven 环境搭建步骤

第一步：下载 Maven

我们直接从 Maven 官方网站下载。为了稳定，推荐使用在企业中广泛应用的 3.8.x 系列或更新的稳定版。

下载 apache-maven-x.x.x-bin.zip 或 apache-maven-x.x.x-bin.tar.gz 压缩包即可。Maven 是一个“绿色”软件，无需安装，直接解压到你希望存放的目录（注意：目录路径中最好不要包含中文或空格）。

第二步：配置环境变量

为了能在计算机的任何位置使用 Maven 命令，我们需要配置环境变量。

  1. 新建 MAVEN_HOME:

    • 右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
    • 在“系统变量”中，点击“新建”。
    • 变量名填写 MAVEN_HOME。
    • 变量值填写你刚刚解压的 Maven 文件夹路径，例如 D:\dev\apache-maven-3.8.8。

  2. 编辑 Path 变量:

    • 在“系统变量”中找到并双击 Path。
    • 点击“新建”，然后输入 %MAVEN_HOME%\bin。
    • 一路点击“确定”保存。

  1. 打开终端 (Terminal)。

  2. 编辑你的 shell 配置文件，通常是 ~/.zshrc (macOS Catalina 及之后) 或 ~/.bash_profile。

    1
    vim ~/.zshrc

  3. 在文件末尾添加以下内容（请将路径替换成你自己的）：

    1
    2
    3
    # MAVEN_HOME
    export MAVEN_HOME=/path/to/your/apache-maven-3.8.8
    export PATH=$PATH:$MAVEN_HOME/bin

  4. 保存文件并使其生效：

    1
    source ~/.zshrc

第三步：验证安装

打开一个新的命令行或终端窗口，输入以下命令：mvn -v
如果能看到类似下面的版本信息，就代表我们的 Maven 环境已经成功搭建。

1
2
3
4
5
Apache Maven 3.8.8 (Random_Hash_String)
Maven home: D:\dev\apache-maven-3.8.8
Java version: 17.0.7, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-17
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

2.1.2. 全局核心配置 (settings.xml)

settings.xml 是 Maven 的全局配置文件，位于 Maven 安装目录的 conf 文件夹下。它定义了本机所有 Maven 项目的通用行为。我们强烈建议对其进行以下三项核心配置。

配置一：指定本地仓库 (Local Repository)

本地仓库是 Maven 用来缓存已下载依赖的地方。默认位置在用户主目录下的 .m2/repository，这通常位于 C 盘。为了避免占用系统盘空间和方便管理，我们应该将其指定到一个自定义的目录。

打开 conf/settings.xml 文件，找到被注释掉的 <localRepository> 标签 (约第 55 行)，将其解开注释并填入你的路径：

1
<localRepository>D:/maven-repository</localRepository>

配置二：配置国内镜像 (Mirror)

Maven 默认从国外的中央仓库下载依赖，速度很慢且不稳定。我们将其指向国内的阿里云镜像，可以极大地提升下载速度。

在 <mirrors> 标签内 (约第 160 行)，添加以下 <mirror> 配置：

1
2
3
4
5
6
7
8
<mirrors>
  <mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

image-20250806211624897

配置三：配置默认 JDK 版本

为了让 Maven 在编译项目时默认使用我们指定的 JDK 版本（例如 JDK 17），可以在 <profiles> 标签内添加一个 profile。

在 <profiles> 标签内 (约第 250 行)，添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
<profiles>

    <!-- JDK 17 配置 -->
    <profile>
        <id>jdk-17</id>
        <activation>
            <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>
    
        <!-- JDK 1.8 配置 -->
    <profile>
        <id>jdk-8</id>
        <activation>
            <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>

    <!-- JDK 11 配置 -->
    <profile>
        <id>jdk-11</id>
        <activation>
            <jdk>11</jdk>
        </activation>
        <properties>
            <maven.compiler.source>11</maven.compiler.source>
            <maven.compiler.target>11</maven.compiler.target>
            <maven.compiler.compilerVersion>11</maven.compiler.compilerVersion>
        </properties>
    </profile>


    <!-- JDK 21 配置 -->
    <profile>
        <id>jdk-21</id>
        <activation>
            <jdk>21</jdk>
        </activation>
        <properties>
            <maven.compiler.source>21</maven.compiler.source>
            <maven.compiler.target>21</maven.compiler.target>
            <maven.compiler.compilerVersion>21</maven.compiler.compilerVersion>
        </properties>
    </profile>
  </profiles>

至此，我们的 Maven 本地环境已全部配置完毕。我们拥有了一个指向自定义仓库、使用高速阿里云镜像、并默认以 JDK 17 编译项目的专业级开发环境。

2.2. IDEA 与本地 Maven 环境的集成

[我们的 Maven 环境已经准备就绪，但还需要最后一步：让我们的主开发工具 IntelliJ IDEA “认识”并使用它。]

2.2.1. 在 IDEA 中指定 Maven

IntelliJ IDEA 自带了一个 Maven 插件，但它是一个“裸奔”的版本，没有我们刚刚精心做的那些配置。因此，必须 将 IDEA 的 Maven 设置指向我们自己的安装目录。

操作步骤：

  1. 打开 IDEA，进入设置界面：
    File -> Settings

  2. 在左侧导航栏中找到：
    Build, Execution, Deployment -> Build Tools -> Maven

  3. 在右侧的面板中，修改以下三项配置：

    • Maven home path: 点击下拉框或文件夹图标，选择我们之前解压的 Maven 目录
      （例如 D:\Maven\apache-maven-3.8.8）。
    • User settings file: 当上一步选择正确后，这一项通常会自动关联到我们修改过的
      conf/settings.xml。如果未自动关联，请勾选 Override 并手动选择它。
    • Local repository: 应自动更新为我们在 settings.xml 中配置的路径
      （例如 D:/maven-repository）。如果未更新，说明 settings.xml 配置有误或未被正确加载。

image-20250806213314119

  1. 打开 IDEA，进入设置界面：
    IntelliJ IDEA -> Preferences

  2. 在左侧导航栏中找到：
    Build, Execution, Deployment -> Build Tools -> Maven

  3. 在右侧的面板中，修改以下三项配置：

    • Maven home path: 点击下拉框或文件夹图标，选择我们之前解压的 Maven 目录
      （例如 /Users/yourname/dev/apache-maven-3.8.8）。
    • User settings file: 当上一步选择正确后，这一项通常会自动关联到我们修改过的
      conf/settings.xml。如果未自动关联，请勾选 Override 并手动选择它。
    • Local repository: 应自动更新为我们在 settings.xml 中配置的路径
      （例如 /Users/yourname/maven-repository）。如果未更新，说明 settings.xml 配置有误或未被正确加载。

重要提示: 如果跳过此步骤，IDEA 将使用其默认设置。这意味着你将无法享受到阿里云镜像带来的高速下载，并且所有依赖都会被下载到 C 盘的用户目录下，这在未来的开发中会造成很多不便。

2.3. 创建第一个 Maven 项目并添加依赖

[万事俱备，现在到了最激动人心的时刻。我们将利用配置好的环境，亲手创建并运行一个真正的 Maven 项目。]

2.3.1. 从创建到运行

第一步：创建 Maven 项目

  1. 在 IDEA 的欢迎界面，点击 New Project。
  2. 在左侧选择 Maven，并确保 Project SDK 已经正确选择了你的 JDK (如 17)。
  3. 点击 Next。
  4. 为你的项目命名，并设置 GroupId 和 ArtifactId。
    • GroupId: 通常是你的组织或个人域名的反写，如 com.mycompany。
    • ArtifactId: 项目的名称，如 my-first-app。
  5. 点击 Finish，等待 IDEA 创建项目并首次初始化。

image-20250806213717131

第二步：解读项目结构

创建完成后，我们会看到一个标准的 Maven 项目目录结构：

1
2
3
4
5
6
7
8
my-maven-project/                  # 项目根目录
├── src/                           # 源码目录
│   ├── main/                      # 主程序目录
│   │   ├── java/                  # 存放主要 Java 源代码
│   │   └── resources/             # 存放配置文件（.properties, .xml 等）
│   └── test/                      # 测试代码目录
│       └── java/                  # 存放单元测试 Java 代码
└── pom.xml                        # Maven 核心配置文件

这个 “约定优于配置” 的结构，保证了所有 Maven 项目在组织方式上的一致性。

第三步：添加依赖并使用

背景: 我们现在需要一个功能，来生成一个通用的唯一识别码 (UUID)。如果自己写会很麻烦，但强大的工具库 Hutool 提供了现成的功能。

解决方案: 我们通过在 pom.xml 中添加 Hutool 的依赖坐标，来“召唤”这个能力。

打开 pom.xml 文件，在 <dependencies> 标签内部添加以下代码片段：

1
2
3
4
5
6
7
<dependencies>
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <version>5.8.27</version>
    </dependency>
</dependencies>

提示: 当你修改 pom.xml 后，IDEA 右上角会弹出一个带有 Maven 图标的小提示，点击它可以让 IDEA 立即加载新的依赖。

image-20250806215304662

验证代码: 现在，我们可以在 src/main/java 下创建一个包和类，并编写以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package com.example;

import cn.hutool.core.util.IdUtil;

public class Main {
    public static void main(String[] args) {
        // 使用 Hutool 的 API 轻松生成一个 UUID 字符串
        String uuid = IdUtil.simpleUUID();
        System.out.println("成功使用 Hutool 生成的 UUID 如下:");
        System.out.println(uuid);
    }
}
// 输出:
// (每次运行结果都不同)
// 成功使用 Hutool 生成的 UUID 如下:
// 4a8c6d3e6f5b4b9e8c7d9a0b1c2d3e4f

运行 main 方法，如果控制台成功打印出一串 UUID，那么恭喜你，你已经完全掌握了 Maven 的基础工作流！

我们通过简单的 声明 而非手动下载，就成功地为项目引入了强大的第三方功能。这就是 Maven 依赖管理的核心魅力。