创建第一个 Maven 项目（二）

六、添加依赖

在 Maven 项目开发过程中，添加依赖是一项常见且关键的操作。通过添加依赖，我们可以引入项目所需的各种库和框架，极大地扩展项目的功能。接下来，我们将以 JUnit 依赖为例，详细介绍如何在 Maven 项目中添加依赖。

（一）打开 pom.xml 文件

在 IntelliJ IDEA 中，打开我们之前创建的 Maven 项目。在项目的导航栏中，找到项目的根目录，其中有一个名为pom.xml的文件，它就是 Maven 项目的核心配置文件。你可以直接双击pom.xml文件来打开它；也可以使用快捷键 "Ctrl + Shift + N"（Windows）或者 "Command + Shift + O"（Mac），在弹出的搜索框中输入 "pom.xml"，然后回车即可快速打开该文件。

（二）在 Maven 仓库中查找依赖

我们以添加 JUnit 依赖为例，JUnit 是一个广泛使用的 Java 单元测试框架，在 Maven 项目中添加 JUnit 依赖可以方便我们编写和运行测试用例。

要查找 JUnit 依赖的坐标，我们可以访问 Maven 仓库的官方网站，例如 Maven Central Repository（https://mvnrepository.com/ ）。在该网站的搜索框中输入 "JUnit"，然后回车，会出现一系列与 JUnit 相关的依赖项。在搜索结果中，我们找到 "JUnit Jupiter API" 和 "JUnit Jupiter Engine"，这两个是 JUnit 5 中的核心依赖。点击进入 "JUnit Jupiter API" 的详情页面，我们可以看到它的坐标信息，包括groupId（org.junit.jupiter）、artifactId（junit-jupiter-api）和最新版本号（例如5.8.2）。同样的方法，我们获取 "JUnit Jupiter Engine" 的坐标信息，groupId也是org.junit.jupiter，artifactId为junit-jupiter-engine，版本号与 "JUnit Jupiter API" 保持一致。

（三）将依赖添加到 pom.xml

打开pom.xml文件后，在<dependencies>标签内添加依赖的坐标信息。将我们在 Maven 仓库中查找到的 JUnit 依赖坐标复制粘贴到<dependencies>标签中，示例代码如下：

<dependencies>

<dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter-api</artifactId>

<version>5.8.2</version>

<scope>test</scope>

</dependency>

<dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter-engine</artifactId>

<version>5.8.2</version>

<scope>test</scope>

</dependency>

</dependencies>

在上述代码中，<groupId>指定了依赖所属的组织，<artifactId>指定了依赖的名称，<version>指定了依赖的版本号，<scope>指定了依赖的作用范围。这里我们将<scope>设置为test，表示这两个依赖只在测试阶段使用，不会被打包到最终的项目中。

（四）等待依赖下载

添加完依赖坐标后，保存pom.xml文件。此时，IDEA 会自动检测到pom.xml文件的变化，并开始下载我们添加的依赖。你可以在 IDEA 的右下角看到一个 Maven 的进度条，显示依赖的下载进度。在下载过程中，可能会出现一些问题：

1. 网络问题：如果下载依赖时出现超时或连接失败的错误，可能是网络不稳定或无法访问 Maven 中央仓库。你可以检查网络连接，或者配置一个国内的镜像源，如阿里云的 Maven 镜像。具体方法是在settings.xml文件中添加以下镜像配置：

<mirrors>

<mirror>

<id>aliyunmaven</id>

<name>阿里云公共仓库</name>

<url>https://maven.aliyun.com/repository/public</url>

<mirrorOf>central</mirrorOf>

</mirror>

</mirrors>

1. 依赖冲突：如果项目中已经存在与新添加依赖冲突的版本，可能会导致下载失败或项目无法正常运行。此时，你需要仔细检查pom.xml文件中已有的依赖和新添加依赖的版本信息，尝试排除冲突的依赖，或者调整依赖的版本，使其相互兼容。例如，如果两个依赖都依赖于同一个库，但版本不同，你可以通过在pom.xml中使用<exclusions>标签来排除其中一个依赖中不需要的库版本，然后手动指定一个统一的版本。

1. 仓库缓存污染问题：当下载某个 jar 包但未下载成功时，会在本地仓库中生成对应的缓存文件（.lastUpdated格式），而当 Maven 检测到缓存文件时是不会重新下载的。所以需要先将缓存文件删除，再去重新下载才行。以下载 log4j 依赖包但下载出现问题中断后的情况为例，本地仓库中对应目录已经出现了缓存文件。此时只需要顺着依赖坐标去本地仓库中的目录寻找，再将缓存文件删除并重新刷新 Maven 下载即可。

耐心等待依赖下载完成，当下载成功后，你就可以在项目中使用这些依赖了。在 IDEA 的项目导航栏中，展开 "External Libraries"（外部库），可以看到我们新添加的 JUnit 依赖已经被成功导入到项目中。

七、编写代码

（一）在 src/main/java 目录下创建包和类

在我们的 Maven 项目中，src/main/java目录是存放 Java 源代码的地方。现在，我们要在这个目录下创建包和类，以实现我们的业务逻辑。

以创建一个简单的HelloWorld类为例，在 IntelliJ IDEA 中，找到项目导航栏中的src/main/java目录，右键点击它，在弹出的菜单中选择 "New"（新建），然后再选择 "Package"（包）。在弹出的输入框中，输入包名，例如com.example.myfirstmavenproject（这里的包名要与我们创建项目时填写的 GroupId 和 ArtifactId 相关联，以保持项目结构的一致性），然后点击 "OK" 按钮，这样就创建好了一个包。

接下来，在刚刚创建的包上右键点击，选择 "New"（新建），再选择 "Java Class"（Java 类）。在弹出的输入框中，输入类名 "HelloWorld"，然后点击 "OK" 按钮。此时，IDEA 会在src/main/java/com/example/myfirstmavenproject目录下创建一个名为HelloWorld.java的文件，文件内容如下：

package com.example.myfirstmavenproject;

public class HelloWorld {

}

这里的package语句声明了该类所属的包，public class HelloWorld则定义了一个名为HelloWorld的公共类。

（二）编写业务逻辑

在HelloWorld类中，我们编写一个简单的输出语句，来展示 Maven 项目的基本代码结构。修改HelloWorld类的代码如下：

package com.example.myfirstmavenproject;

public class HelloWorld {

public static void main(String[] args) {

System.out.println("Hello, Maven! This is my first Maven project.");

}

}

在这段代码中，main方法是 Java 应用程序的入口点，System.out.println是 Java 的标准输出语句，用于在控制台输出指定的字符串。这里我们输出了 "Hello, Maven! This is my first Maven project."，表示这是我们在 Maven 项目中编写的第一个简单程序。通过这样一个简单的示例，我们可以看到 Maven 项目中 Java 类的基本结构，以及如何在类中编写业务逻辑代码。在实际项目开发中，我们会在src/main/java目录下创建更多的包和类，编写复杂的业务逻辑，实现各种功能。

八、构建和运行项目

（一）使用 Maven 命令构建项目

在完成代码编写和依赖添加后，我们需要使用 Maven 命令对项目进行构建。Maven 提供了一系列丰富的命令，用于完成不同的构建任务。在 IntelliJ IDEA 中，我们可以通过 IDEA 的 Terminal 来执行这些 Maven 命令。

1. 常用 Maven 命令介绍：

• • mvn clean：这个命令用于清除项目构建生成的文件，通常是清除target目录下的内容。在重新构建项目之前，执行mvn clean可以确保生成的是最新的构建结果，避免因旧文件残留而导致的问题。例如，当我们对项目的配置或代码进行了较大修改时，先执行mvn clean可以保证新的构建不受旧文件的影响。

• • mvn compile：该命令用于编译项目的源代码。它会将src/main/java目录下的 Java 文件编译成字节码文件（.class文件），并将编译结果输出到target/classes目录中。这是项目构建的基本步骤，只有成功编译源代码，项目才能进行后续的测试和打包等操作。

• • mvn test：用于运行项目的测试用例。Maven 会执行src/test/java目录下的测试类，通过 JUnit、TestNG 等测试框架来验证项目的功能是否正确。在开发过程中，经常运行mvn test可以及时发现代码中的问题，保证项目的质量。例如，当我们修改了某个功能模块的代码后，执行mvn test可以检查该模块的测试用例是否仍然通过，确保修改没有引入新的错误。

• • mvn package：这个命令会将编译后的代码打包成相应的文件格式。对于 Java 应用程序，通常会打包成 JAR 文件；对于 Web 项目，则会打包成 WAR 文件。打包后的文件会存放在target目录下，例如我们的项目打包后会生成my - first - maven - project - 1.0 - SNAPSHOT.jar（假设项目的 ArtifactId 为my - first - maven - project，版本号为1.0 - SNAPSHOT）。打包后的文件可以方便地进行部署和分发。

• • mvn install：在mvn package的基础上，mvn install会将打包后的文件安装到本地 Maven 仓库中。这样，其他项目就可以通过 Maven 依赖管理来引用这个项目。例如，当我们开发了一个通用的工具类库，并将其打包安装到本地仓库后，其他项目在pom.xml中添加相应的依赖，就可以使用这个工具类库了。

1. 在 IDEA 的 Terminal 中执行 Maven 命令：

• • 打开 IntelliJ IDEA，进入我们创建的 Maven 项目。在 IDEA 的底部工具栏中，找到并点击 "Terminal" 按钮，打开终端窗口。

• • 在终端窗口中，默认的路径是项目的根目录，也就是包含pom.xml文件的目录。此时，我们可以直接输入 Maven 命令。例如，要执行mvn clean命令，只需在终端中输入 "mvn clean"，然后回车。IDEA 会执行该命令，并在终端中显示命令的执行过程和结果。

• • 如果要执行多个 Maven 命令，例如先执行mvn clean，再执行mvn compile，可以在终端中依次输入这两个命令，每个命令执行完成后再输入下一个。也可以使用分号将多个命令连接起来，一次性执行，例如 "mvn clean; mvn compile"。但需要注意的是，这种方式下，如果前面的命令执行失败，后面的命令仍然会继续执行，可能会导致错误的结果。所以，在实际使用中，建议根据具体情况选择合适的方式。

（二）运行项目

项目构建完成后，就可以运行项目来验证其功能了。运行项目的方式取决于项目的类型，下面分别介绍 Java 应用程序和 Web 项目的运行方法。

1. 运行 Java 应用程序：

如果我们创建的是一个 Java 应用程序，并且在src/main/java目录下定义了包含main方法的类（例如前面创建的HelloWorld类），那么可以直接在 IDEA 中运行这个类。

• • 在 IDEA 的项目导航栏中，找到包含main方法的类文件，例如HelloWorld.java。

• • 右键点击该类文件，在弹出的菜单中选择 "Run 'HelloWorld.main ()'" 选项，或者直接使用快捷键 "Shift + F10"（Windows 和 Linux 系统）、"Control + R"（Mac 系统）。

• • IDEA 会启动 Java 虚拟机，执行main方法中的代码，在控制台中输出结果。例如，对于HelloWorld类，控制台会输出 "Hello, Maven! This is my first Maven project."。

1. 运行 Web 项目：

如果我们创建的是一个 Web 项目，需要配置 Tomcat 服务器来运行项目。以下是在 IDEA 中配置 Tomcat 并运行 Web 项目的步骤：

• • 下载和安装 Tomcat ：首先，需要从 Apache Tomcat 官方网站（https://tomcat.apache.org/download - tomcat.cgi ）下载 Tomcat 的安装包。根据自己的操作系统选择合适的版本，例如 Windows 系统可以下载apache - tomcat - 9.0.64.zip（以 9.0.64 版本为例）。下载完成后，将压缩包解压到指定的目录，例如C:\apache - tomcat - 9.0.64。

• • 配置 Tomcat 在 IDEA 中：

• • • 打开 IntelliJ IDEA，进入 Web 项目。点击菜单栏中的 "Run"（运行），然后选择 "Edit Configurations"（编辑配置）。

• • • 在弹出的 "Run/Debug Configurations"（运行 / 调试配置）窗口中，点击左上角的 "+" 按钮，在下拉菜单中选择 "Tomcat Server"（Tomcat 服务器），然后选择 "Local"（本地）。

• • • 在 "Tomcat Server" 配置页面中，"Name"（名称）可以保持默认，也可以自定义一个容易识别的名称。在 "Server" 选项卡中，设置 "Tomcat home directory"（Tomcat 主目录）为前面解压 Tomcat 的目录，例如C:\apache - tomcat - 9.0.64。如果 Tomcat 需要用户名和密码进行管理（例如部署应用时），可以在 "User" 和 "Password" 字段中填写相应的信息。

• • • 切换到 "Deployment"（部署）选项卡，点击右上角的 "+" 按钮，选择 "Artifact"（工件）。在弹出的菜单中，选择我们的 Web 项目对应的工件，例如my - first - maven - project:war exploded（如果项目是打包成 WAR 文件并以爆炸式部署，即展开的目录形式部署）。如果项目是打包成普通的 WAR 文件，可以选择my - first - maven - project:war。选择好工件后，点击 "OK" 按钮。

• • 运行 Web 项目 ：配置完成后，点击 "Run/Debug Configurations" 窗口中的 "OK" 按钮保存配置。然后，点击 IDEA 工具栏中的绿色三角形 "Run" 按钮，或者使用快捷键 "Shift + F10"（Windows 和 Linux 系统）、"Control + R"（Mac 系统）。IDEA 会启动 Tomcat 服务器，并部署我们的 Web 项目。当 Tomcat 启动成功后，在浏览器中输入项目的访问地址，例如http://localhost:8080/my - first - maven - project（假设 Tomcat 的默认端口是 8080，项目的上下文路径是my - first - maven - project），就可以访问 Web 项目了。

通过以上步骤，我们可以使用 Maven 命令构建项目，并根据项目的类型运行项目，从而验证项目的功能是否正常。在实际开发中，构建和运行项目是一个反复的过程，我们需要不断地修改代码、添加依赖、构建项目并运行测试，以确保项目的质量和稳定性。

九、常见问题及解决方法

在创建和使用 Maven 项目的过程中，我们可能会遇到各种各样的问题。下面将针对一些常见问题进行分析，并提供相应的解决方法。

（一）依赖下载失败

1. 网络问题：

• • 原因分析：网络不稳定、代理设置错误或无法访问 Maven 中央仓库等网络问题，都可能导致依赖下载失败。比如，当网络连接中断或速度过慢时，Maven 在下载依赖的过程中就可能会出现超时错误。如果设置了代理服务器，但代理配置不正确，也会使 Maven 无法正常连接到仓库。

• • 解决方法：首先，检查网络连接是否正常，可以通过访问其他网站来验证。如果是代理问题，需要正确配置代理。在 Maven 的 settings.xml 文件中，添加或修改代理配置。例如：

<proxies>

<proxy>

<id>my-proxy</id>

<active>true</active>

<protocol>http</protocol>

<host>proxy.example.com</host>

<port>8080</port>

<username>proxyuser</username>

<password>proxypassword</password>

</proxy>

</proxies>

其中，<host>是代理服务器的地址，<port>是代理服务器的端口，<username>和<password>是代理服务器的认证信息（如果需要认证）。如果没有代理，可以在 settings.xml 中添加阿里云镜像来提高下载速度，配置如下：

<mirrors>

<mirror>

<id>aliyunmaven</id>

<name>阿里云公共仓库</name>

<url>https://maven.aliyun.com/repository/public</url>

<mirrorOf>central</mirrorOf>

</mirror>

</mirrors>

1. 仓库配置问题：

• • 原因分析：Maven 的仓库配置错误，如本地仓库路径设置不正确、远程仓库地址不可用等，也会导致依赖下载失败。例如，本地仓库路径设置为一个不存在的目录，Maven 就无法将下载的依赖存储到该目录；远程仓库地址错误或仓库服务器宕机，Maven 就无法从该仓库下载依赖。

• • 解决方法：检查 Maven 的配置文件 settings.xml，确保本地仓库路径设置正确。如果本地仓库路径设置错误，修改<localRepository>标签的值为正确的路径。例如：

<localRepository>C:\Users\yourusername\.m2\repository</localRepository>

如果远程仓库地址不可用，可以尝试更换其他可靠的远程仓库，或者等待仓库服务器恢复正常。

3. 依赖坐标错误：

• 原因分析：在 pom.xml 文件中声明依赖时，如果依赖的坐标（groupId、artifactId、version）填写错误，Maven 就无法找到对应的依赖，从而导致下载失败。比如，将 groupId 写错，或者使用了一个不存在的版本号。

• 解决方法 ：仔细检查 pom.xml 文件中依赖的坐标信息，确保其准确无误。可以通过 Maven 仓库的官方网站（如https://mvnrepository.com/ ）来查找正确的依赖坐标。例如，要添加 JUnit 5 的依赖，如果发现下载失败，检查<groupId>是否为org.junit.jupiter，<artifactId>是否为junit-jupiter-api或junit-jupiter-engine，版本号是否正确。

1. 仓库缓存污染问题：

• • 原因分析：当下载某个 jar 包但未下载成功时，会在本地仓库中生成对应的缓存文件（.lastUpdated格式），而当 Maven 检测到缓存文件时是不会重新下载的。这就导致即使网络和依赖坐标等都正确，也无法下载到正确的依赖。

• • 解决方法：先将缓存文件删除，再去重新下载。顺着依赖坐标去本地仓库中的目录寻找，将对应的.lastUpdated文件删除，然后在 IDEA 中刷新 Maven 项目，Maven 就会重新尝试下载依赖。例如，下载 log4j 依赖包时出现问题中断，本地仓库中对应目录出现了缓存文件，此时进入本地仓库中 log4j 依赖的对应目录，删除.lastUpdated文件，然后重新刷新 Maven 下载即可。

（二）项目构建报错

1. 语法错误：

• • 报错信息示例："error: illegal start of expression"，通常表示 Java 代码中存在语法错误，如缺少分号、括号不匹配、关键字拼写错误等。例如，在定义方法时，忘记写方法的返回值类型，或者在使用变量前未进行声明。

• • 解决思路：仔细检查报错信息中指向的代码行，找出语法错误并进行修正。IDEA 通常会在代码编辑器中用红色波浪线标记出语法错误的位置，将鼠标悬停在错误处，会显示详细的错误提示信息。根据提示信息，对代码进行相应的修改。例如，如果提示缺少分号，就在相应的语句末尾添加分号；如果括号不匹配，检查括号的数量和位置，确保括号正确配对。

1. 依赖冲突：

• • 报错信息示例："java.lang.NoClassDefFoundError" 或 "java.lang.ClassNotFoundException"，当项目中存在依赖冲突时，可能会导致某些类无法被正确加载，从而抛出这些异常。例如，项目中同时依赖了两个不同版本的同一个库，而这两个版本之间存在不兼容的情况。

• • 解决思路：使用 IDEA 自带的功能或插件来排查和解决依赖冲突。可以打开 Maven 菜单，点击 "show dependencies"，展示项目的依赖关系树，红色的线通常表示冲突的依赖。选中冲突的包，然后右键选择 "exclude"，可以排除冲突的依赖。也可以安装插件 Maven Helper，安装后打开 pom.xml 文件并点击依赖分析，左侧列表会列出依赖，点击依赖后右边框体会展示冲突情况。对着冲突内容点击鼠标右键选择 "Exclude"，即可排除冲突。此外，还可以使用 Maven 命令 "mvn dependency:tree -Dverbose"，以树形结构展现项目中的依赖，通过搜索 "conflict" 来查找冲突的依赖，然后在 pom.xml 中手动排除依赖。

1. Maven 插件配置错误：

• • 报错信息示例："Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile"，表示 Maven 在执行编译插件时出现错误，可能是插件配置不正确，如插件版本不兼容、配置参数错误等。例如，在配置 Maven 编译插件时，指定的 Java 版本与实际安装的 Java 版本不一致。

• • 解决思路：检查 pom.xml 文件中 Maven 插件的配置信息，确保插件的版本正确，并且配置参数符合项目的需求。如果是插件版本问题，可以尝试更新或降级插件版本；如果是配置参数错误，根据插件的文档，修改配置参数。例如，配置 Maven 编译插件时，确保<source>和<target>标签指定的 Java 版本与实际安装的 Java 版本一致：

<build>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

<version>3.8.1</version>

<configuration>

<source>11</source>

<target>11</target>

</configuration>

</plugin>

</plugins>

</build>

1. 缺少依赖或依赖范围错误：

• • 报错信息示例："package xxx does not exist"，当项目中使用了某个包，但该包所对应的依赖没有正确添加到项目中，或者依赖的范围设置错误，就会出现这种错误。例如，在代码中使用了org.springframework包下的类，但项目的 pom.xml 中没有添加 Spring 相关的依赖，或者依赖的<scope>设置为test，而在主代码中使用了该依赖。

• • 解决思路：检查 pom.xml 文件，确保项目所需的依赖都已正确添加，并且依赖的范围设置合理。如果缺少依赖，在<dependencies>标签内添加相应的依赖坐标；如果依赖范围错误，修改<scope>标签的值。例如，如果在主代码中使用了org.springframework包下的类，在 pom.xml 中添加 Spring 的依赖：

<dependencies>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context</artifactId>

<version>5.3.10</version>

</dependency>

</dependencies>

并且确保<scope>标签的值为compile（默认值，表示在编译、测试和运行时都需要该依赖），而不是test（表示仅在测试时需要该依赖）。

通过对这些常见问题的分析和解决方法的介绍，希望能帮助大家在创建和使用 Maven 项目时，快速解决遇到的问题，顺利推进项目的开发。

十、总结

在本次探索之旅中，我们深入了解了 Maven 这一强大工具，并成功创建了第一个 Maven 项目。从 Maven 的定义和优势出发，明确了它在 Java 项目管理中的核心地位。通过细致的准备工作，包括安装 Java JDK、Maven 以及选择合适的开发工具 IntelliJ IDEA，搭建起了坚实的开发环境。

在创建项目的过程中，我们一步步完成了项目的创建、结构解析、依赖添加、代码编写以及构建和运行。每一个环节都紧密相连，共同构成了一个完整的 Maven 项目开发流程。同时，我们也对项目构建过程中可能出现的依赖下载失败、项目构建报错等常见问题进行了分析，并提供了相应的解决方法，帮助大家在实际开发中能够快速应对和解决问题。

然而，Maven 的强大功能远不止于此，它还有许多高级特性等待我们去探索。比如，使用 profiles 根据不同的环境定制构建配置，实现开发、测试和生产环境的差异化设置；通过分模块构建，将大型项目拆分为多个独立的模块，提高项目的可维护性和可扩展性；利用 Maven 的依赖传递和冲突解决机制，更加灵活地管理项目依赖。

希望大家在掌握了创建第一个 Maven 项目的基础上，能够继续深入学习 Maven 的高级特性，不断提升自己的项目管理和开发能力。在未来的 Java 开发中，充分发挥 Maven 的优势，提高开发效率，打造更加优质的项目。