Maven：从零开始的实战部署

Maven 是 Java 项目最核心的构建和依赖管理工具。从创建项目到最终打包，完整的流程可以分为以下五个阶段：环境准备、项目创建、依赖管理、构建与测试、打包与部署。

以下是基于 2026 年主流开发环境（JDK 17/21, Maven 3.9+, IDEA 2025+）的详细操作指南。

第一阶段：环境准备 (Installation & Configuration)

在使用 Maven 之前，必须确保本地环境配置正确，特别是国内镜像加速，否则依赖下载会非常慢。

1. 前置要求

• JDK: 确保已安装 JDK (推荐 JDK 17 或 21)，并配置好 JAVA_HOME。
  • 验证：java -version
• Maven: 下载 Apache Maven (推荐 3.9.x 版本)。
  • 下载地址：https://maven.apache.org/download.cgi
  • 解压后配置环境变量 MAVEN_HOME，并将 %MAVEN_HOME%\bin 加入 PATH。
  • 验证：mvn -version

2. 核心配置 (关键步骤)

修改 Maven 的配置文件 settings.xml (通常位于 conf/settings.xml 或 ~/.m2/settings.xml)，配置本地仓库路径和阿里云镜像。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" ...>
  
  <!-- 1. 配置本地仓库路径 (可选，默认在 C盘用户目录下，建议改到空间大的磁盘) -->
  <localRepository>D:\DevTools\MavenRepo</localRepository>

  <!-- 2. 配置阿里云镜像 (加速下载，必配) -->
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <name>Aliyun Public</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>

  <!-- 3. 配置 JDK 编译版本 (全局默认)：选择你环境变量的Java版本 -->
  <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.release>17</maven.compiler.release>
      </properties>
    </profile>
  </profiles>

</settings>

3. IDEA 集成

• 打开 IntelliJ IDEA -> Settings (或 Preferences) -> Build, Execution, Deployment -> Build Tools -> Maven。
• Maven home path: 选择你安装的 Maven 目录。
• User settings file: 选择上面修改过的 settings.xml。
• Local repository: 确认指向你配置的本地仓库路径。

第二阶段：创建项目 (Project Creation)

可以通过命令行或 IDEA 图形界面创建，推荐新手使用 IDEA，更直观。

方法 A：使用 IDEA 创建 (推荐)

1. 点击 File -> New -> Project。
2. 左侧选择 Maven。
3. 填写 GroupId (组织名，如 com.example) 和 ArtifactId (项目名，如 my-demo)。
4. 选择 archetype (原型)：
   • 简单项目：选择 maven-archetype-quickstart (生成含源码和测试的模板)。
   • Web 项目：选择 maven-archetype-webapp (生成 webapp 目录结构)。
   • 注：现代 Spring Boot 项目通常直接选 Spring Initializr 或创建空 Maven 项目后手动改 pom。
5. 点击 Create，IDEA 会自动生成标准目录结构并下载初始依赖。

方法 B：使用命令行创建

# 创建一个标准的 Java 项目
mvn archetype:generate -DgroupId=com.example -DartifactId=my-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

标准目录结构解析

创建成功后，你会看到如下结构：

my-demo/
├── src/
│   ├── main/
│   │   ├── java/          # 存放源代码
│   │   └── resources/     # 存放配置文件 (application.yml, properties)
│   └── test/
│       ├── java/          # 存放测试代码
│       └── resources/     # 存放测试配置
├── pom.xml                # 【核心】项目对象模型，管理依赖和构建配置
└── target/                # 【输出】编译、打包后的文件存放处 (自动生成)

第三阶段：依赖管理 (Dependency Management)

Maven 的核心在于 pom.xml。你需要在此文件中声明项目所需的第三方库。

1. 添加依赖

在 <dependencies> 标签内添加。例如添加 MySQL 驱动和 JUnit 测试库：

<project>
    <!-- ... 其他坐标信息 ... -->
    
    <dependencies>
        <!-- MySQL 驱动 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.3.0</version>
            <scope>runtime</scope> <!-- 运行时生效，编译不需要 -->
        </dependency>

        <!-- JUnit 测试框架 -->
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.13.2</version>
            <scope>test</scope> <!-- 仅测试阶段生效 -->
        </dependency>
        
        <!-- Lombok (简化代码) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
            <scope>provided</scope> <!-- 编译时生效，打包时不包含 -->
        </dependency>
    </dependencies>
</project>

2. 刷新依赖

• IDEA: 修改 pom.xml 后，点击右上角的 小浮窗 (Load Maven Changes) 或右侧 Maven 面板的 刷新图标。
• 命令行: 执行 mvn idea:idea (旧版) 或重新导入项目。

3. 常见 Scope 说明

• compile (默认): 编译、测试、运行都有效 (如 Spring Core)。
• test: 仅测试有效 (如 JUnit)。
• provided: 编译、测试有效，运行时由容器提供 (如 Servlet API, Tomcat 自带)。
• runtime: 编译无效，测试和运行有效 (如 MySQL 驱动，代码里只调接口，实现类在运行时加载)。

第四阶段：构建与测试 (Build & Test)

Maven 拥有标准的生命周期 (Lifecycle)。最常用的命令如下：

1. 常用命令详解

在终端进入项目根目录（包含 pom.xml 的目录）执行：

2. 典型操作流程

通常我们不会单独执行上述命令，而是执行组合命令：

# 标准发布流程：清理 -> 编译 -> 测试 -> 打包
mvn clean package

• 跳过测试: 如果测试用例有问题或想快速打包，可加 -DskipTests 或 -Dmaven.test.skip=true。

mvn clean package -DskipTests

第五阶段：打包与产物 (Packaging & Artifacts)

执行 mvn package 后，查看 target 目录。

1. 产物类型

根据 pom.xml 中 <packaging> 标签的不同，生成的文件不同：

• Jar (<packaging>jar</packaging>): 默认值。生成 my-demo-1.0-SNAPSHOT.jar。用于普通 Java 项目或微服务。
• War (<packaging>war</packaging>): 生成 my-demo-1.0-SNAPSHOT.war。用于传统 Web 项目，需部署到 Tomcat/Jetty。
• Pom (<packaging>pom</packaging>): 通常用于父工程，只管理依赖，不生成代码包。

2. 可执行 Jar (Spring Boot 特例)

如果是 Spring Boot 项目，pom.xml 需要引入 spring-boot-maven-plugin，这样 package 生成的 Jar 包可以直接通过 java -jar 运行：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

• 运行打包后的程序:

java -jar target/my-demo-1.0-SNAPSHOT.jar

进阶：多模块项目管理 (Multi-Module)

对于大型项目，通常采用父子模块结构。

1. 父工程 (Parent):
   • packaging 设为 pom。
   • 使用 <modules> 标签管理子模块。
   • 使用 <dependencyManagement> 统一版本号，子模块引用时不需写版本号。
2. 子工程 (Child):
   • 使用 <parent> 标签继承父工程。
   • 只需声明 artifactId 和需要的依赖。

父工程 pom.xml 示例:

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

    <modules>
        <module>common-module</module>
        <module>service-module</module>
        <module>web-module</module>
    </modules>
    
    <!-- 统一管理版本 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>fastjson</artifactId>
                <version>2.0.40</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

常见问题排查 (Troubleshooting)

1. mvn 不是内部或外部命令:
   • 检查环境变量 PATH 是否包含 %MAVEN_HOME%\bin。
   • 重启终端或 IDEA。
2. 依赖下载失败 (Could not transfer artifact):
   • 检查网络，确认 settings.xml 中是否配置了阿里云镜像。
   • 删除本地仓库中对应的 .lastUpdated 文件，然后刷新重试。
3. 编译报错 invalid target release: XX:
   • IDEA 的 Project Structure 中设置的 SDK 版本与 pom.xml 中 maven.compiler 版本不一致。确保两者匹配（如都用 17）。
4. 中文乱码:
   • 在 pom.xml 的 <properties> 中添加：

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

通过以上流程，你可以完成从零开始创建一个规范的 Maven 项目，管理依赖，并最终将其打包为可交付的软件制品。