IDEA + Maven 环境配置超详细教程（图文详解）

摘要： 本文详细讲解如何在Windows环境下配置Maven本地仓库，并在IntelliJ IDEA中完成Maven环境搭建，为后续Hadoop/HDFS Java开发做好准备。步骤清晰，新手友好，建议收藏！

一、前言

在进行Hadoop生态相关的Java开发时，我们经常需要使用Maven来管理项目依赖。Maven不仅能帮我们自动下载和管理jar包，还能规范项目结构，大大提高开发效率。

本文将手把手教你完成以下配置：

✅ Maven本地仓库搭建
✅ IDEA中Maven环境配置
✅ 新建Maven项目并添加Hadoop依赖

二、准备工作

2.1 所需软件包

软件	说明	下载地址
apache-maven-3.8.1	Maven构建工具	Apache Maven官网
IntelliJ IDEA	Java集成开发环境	JetBrains官网
Hadoop Windows依赖	hadoop-3.1.0	课程资料包

注意： 所有路径不要包含中文，避免后续出现各种奇怪的错误！

三、Maven本地仓库搭建

3.1 创建Maven目录

在D盘（或其他非系统盘）创建一个名为 maven 的文件夹：

3.2 解压Maven

将下载的 apache-maven-3.8.1.zip 复制到 D:\maven 目录下，并解压：

3.3 创建本地仓库目录

在 D:\maven 文件夹中，手动创建一个名为 repository 的文件夹，用于存放后续下载的jar包：

复制代码

D:\
└── maven\
    ├── apache-maven-3.8.1\
    └── repository\    ← 本地仓库（初始为空，后续自动填充）

3.4 修改settings.xml配置

步骤1： 打开 D:\maven\apache-maven-3.8.1\conf\settings.xml 文件，用记事本或Notepad++打开。

步骤2： 找到第55行左右，找到 <localRepository> 标签（默认被注释），修改为：

xml 复制代码

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

提示： 路径中使用正斜杠 / 或双反斜杠 \\，不要使用单反斜杠 \。

步骤3（可选，推荐）： 配置阿里云镜像，加速依赖下载。在 <mirrors> 标签内添加：

xml 复制代码

<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

四、IDEA中配置Maven

4.1 打开IDEA设置

打开IDEA，点击顶部菜单栏：

复制代码

File → Settings

快捷键： Ctrl + Alt + S

4.2 配置Maven路径

在设置面板左侧导航栏中，依次展开：

复制代码

Build, Execution, Deployment → Build Tools → Maven

需要修改的三个关键配置项：

配置项	设置值	说明
Maven home path	`D:/maven/apache-maven-3.8.1`	Maven安装目录
User settings file	`D:\maven\apache-maven-3.8.1\conf\settings.xml`	配置文件路径
Local repository	`D:\maven\repository`	本地仓库路径（修改settings.xml后自动识别）

操作步骤：

点击 Maven home path 右侧的文件夹图标，选择 D:\maven\apache-maven-3.8.1
勾选 User settings file 的 Override ，选择 settings.xml
勾选 Local repository 的 Override ，选择 repository 文件夹

4.3 应用配置

点击右下角的 Apply 按钮，再点击 OK 保存设置。

五、配置新项目默认设置（重要！）

上述配置仅对当前项目生效，为了让以后新建的每个项目都使用这个Maven配置，还需要进行以下操作：

5.1 打开新项目默认设置

复制代码

File → New Projects Setup → Settings for New Projects

注意： 不同版本IDEA菜单可能略有不同，老版本可能是 File → Other Settings → Settings for New Projects

5.2 重复Maven配置

在弹出的设置窗口中，再次按照 4.2节 的步骤配置Maven路径：

复制代码

Build, Execution, Deployment → Build Tools → Maven

设置完全相同的三个路径，点击 Apply → OK。

这一步非常关键！ 如果不配置，每次新建项目都会使用IDEA内置的Maven，导致依赖下载到默认位置（C盘用户目录下），占用系统盘空间。

六、创建Maven项目并添加依赖

6.1 新建项目

选择 Maven 项目类型，勾选 Create from archetype （可选，新手建议不勾选，使用空项目），点击 Next。

填写项目信息：

字段	示例值	说明
Name	`hdfs-demo`	项目名称
Location	`D:\IdeaProjects\hdfs-demo`	项目存放路径
GroupId	`com.hadoop`	组织标识（公司域名反写）
ArtifactId	`hdfs-demo`	项目唯一标识
Version	`1.0-SNAPSHOT`	版本号（默认即可）

点击 Finish 完成创建。

6.2 项目结构说明

创建完成后，项目目录结构如下：

复制代码

hdfs-demo/
├── src/
│   ├── main/
│   │   ├── java/          ← 存放Java源代码
│   │   └── resources/     ← 存放配置文件
│   └── test/
│       └── java/          ← 存放测试代码
├── pom.xml                ← Maven核心配置文件（重要！）
└── hdfs-demo.iml

6.3 添加Hadoop依赖

打开 pom.xml 文件，在 <dependencies> 标签内添加以下依赖：

xml 复制代码

<dependencies>
    <!-- Hadoop客户端依赖，用于HDFS操作 -->
    <dependency>
        <groupId>org.apache.hadoop</groupId>
        <artifactId>hadoop-client</artifactId>
        <version>3.1.3</version>
    </dependency>
    
    <!-- JUnit单元测试 -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.12</version>
        <scope>test</scope>
    </dependency>
    
    <!-- SLF4J日志门面 -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-log4j12</artifactId>
        <version>1.7.30</version>
    </dependency>
</dependencies>

完整pom.xml示例：

xml 复制代码

<?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.hadoop</groupId>
    <artifactId>hdfs-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Hadoop客户端 -->
        <dependency>
            <groupId>org.apache.hadoop</groupId>
            <artifactId>hadoop-client</artifactId>
            <version>3.1.3</version>
        </dependency>
        
        <!-- JUnit测试 -->
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.12</version>
            <scope>test</scope>
        </dependency>
        
        <!-- 日志 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
            <version>1.7.30</version>
        </dependency>
    </dependencies>
</project>

6.4 刷新Maven项目

添加依赖后，IDEA右下角会弹出提示：

点击 Import Changes ，IDEA会自动从远程仓库下载依赖jar包到本地仓库 D:\maven\repository。

注意： 首次下载依赖需要联网，如果依赖显示红色，说明正在下载中，请耐心等待。也可以在右侧Maven面板点击刷新按钮 🔄。

下载完成后，在右侧Maven面板可以看到：

复制代码

Maven
└── hdfs-demo
    └── Dependencies
        ├── org.apache.hadoop:hadoop-client:3.1.3
        ├── junit:junit:4.12
        └── org.slf4j:slf4j-log4j12:1.7.30

七、配置日志文件

在项目的 src/main/resources 目录下，创建日志配置文件：

步骤1： 右键 resources 文件夹 → New → File

步骤2： 命名为 log4j.properties

步骤3： 填入以下内容：

properties 复制代码

# 日志级别：INFO显示INFO、WARNING、ERROR；WARNING显示WARNING、ERROR；ERROR只显示ERROR
log4j.rootLogger=INFO, stdout

# 控制台输出
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - %m%n

# 文件输出
log4j.appender.logfile=org.apache.log4j.FileAppender
log4j.appender.logfile.File=target/spring.log
log4j.appender.logfile.layout=org.apache.log4j.PatternLayout
log4j.appender.logfile.layout.ConversionPattern=%d %p [%c] - %m%n

八、验证配置是否成功

8.1 创建测试类

在 src/main/java 下新建包 com.hadoop，再创建类 HadoopTest：

java 复制代码

package com.hadoop;

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.fs.FileSystem;
import org.apache.hadoop.fs.Path;
import java.net.URI;

public class HadoopTest {
    public static void main(String[] args) throws Exception {
        // 1. 创建配置对象
        Configuration conf = new Configuration();
        
        // 2. 获取HDFS文件系统对象
        FileSystem fs = FileSystem.get(
            new URI("hdfs://192.168.128.137:8020"), 
            conf, 
            "bigdata0102"
        );
        
        // 3. 测试：创建目录
        fs.mkdirs(new Path("/test"));
        System.out.println("目录创建成功！");
        
        // 4. 关闭资源
        fs.close();
    }
}

8.2 运行测试

右键运行 main 方法，如果控制台输出：

复制代码

目录创建成功！

说明Maven环境配置成功，且能正常连接HDFS！

九、常见问题汇总

Q1：依赖下载速度慢或失败？

解决： 在 settings.xml 中配置阿里云镜像（见3.4节），或检查网络连接。

Q2：pom.xml中依赖显示红色？

解决： 这是正常现象，表示依赖正在下载。等待片刻，或点击Maven面板刷新按钮。如果长时间不变红，检查Maven配置是否正确。

Q3：报错 "Cannot resolve symbol 'hadoop'"？

解决：

检查 pom.xml 中依赖坐标是否正确
检查Maven本地仓库路径是否配置正确
点击 File → Invalidate Caches / Restart 清除缓存重启

Q4：运行时提示 "HADOOP_HOME and hadoop.home.dir are unset"？

解决： 需要将Windows依赖包中的 hadoop-3.1.0 解压到非中文路径，并配置系统环境变量 HADOOP_HOME，将 %HADOOP_HOME%\bin 加入 PATH。

十、总结

本文完整讲解了Maven环境配置的流程：

步骤	内容	关键路径
1	创建Maven目录	`D:\maven`
2	解压Maven并创建repository	`D:\maven\repository`
3	修改settings.xml	配置本地仓库路径
4	IDEA中配置Maven	`File → Settings → Maven`
5	配置新项目默认设置	`File → New Projects Setup`
6	创建项目并添加依赖	编辑 `pom.xml`
7	配置日志文件	`log4j.properties`

配置好Maven环境后，就可以愉快地进行Hadoop/HDFS的Java开发了！后续文章将详细介绍HDFS的Java API操作，敬请期待。

如果觉得本文对你有帮助，欢迎点赞 👍、收藏 ⭐、评论 💬！你的支持是我持续更新的动力！