IDEA 2025.3.3 新建 Maven 项目：JDK、镜像与依赖配置

如果你刚装好 IDEA 2025.3.3，想从零建一个 Maven 项目，大概会跟我第一次上手时一样：跟着网上的老教程点了半天，发现按钮位置完全对不上，好不容易建完项目，一运行又是依赖下载超时、JDK 报错。这个版本的新项目向导改过好几轮，很多旧截图已经没参考价值了。这篇教程就基于 2025.3.3 的界面，从 JDK、Maven 安装讲到项目创建、跑通第一个 Java 程序，把每一步为什么这么做也说清楚，新手照着做就能复现，不用再猜。

这篇内容适合完全没接触过 Maven 的人，也适合那些会用 IDEA 写单文件、但从来没搞清楚 Maven 到底在干嘛的同学。社区版 IDEA 完全够用，本教程全流程不依赖旗舰版功能，放心操作。

1. 动手前的准备：先把 JDK 和 Maven 装在正确的位置

很多新手一上来就打开 IDEA 点 New Project，然后卡在“没有可用 JDK”或者“Maven 导入依赖一直转圈”。其实这些问题的根子都在环境准备阶段——JDK 没装对、Maven 路径有中文、镜像源没配。这一节花十分钟搞定，后面全程顺畅。

1.1 JDK 版本选错，后面每一步都要返工

IDEA 2025.3.3 对 JDK 的最低要求是 17，但我建议你直接装 JDK 21。原因很简单：17 是长期支持版本，21 也是长期支持版本而且更主流，Spring Boot 3 系列项目基本都是 17 起步，你现在学的就是以后工作要用的，没必要从老版本开始。

JDK 去哪下？两个途径：

• Oracle 官网下载 Oracle JDK，版本稳定，但下载页面容易迷路。
• Adoptium 官网（aka.ms/install-jdk 或 adoptium.net）下载 Eclipse Temurin，开源免费，企业里用得非常普遍。

我一般推荐 Temurin，省得注册账号。下载时选 Windows x64 的 .msi 或 .zip 都行，.msi 安装包会自动帮你配好环境变量，适合新手；.zip 解压后要手动配 JAVA_HOME，我下面会写。

安装完成后打开命令提示符（cmd），输入：

java -version

如果显示类似openjdk version "21.0.2"这样的信息，说明 JDK 已经可用。如果提示“不是内部或外部命令”，说明 JAVA_HOME 或 PATH 没配好。检查步骤：

1. 右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量。
2. 在系统变量里新建 JAVA_HOME，值为 JDK 安装目录，比如C:\Program Files\Eclipse Adoptium\jdk-21.0.2。
3. 编辑 Path 变量，新增%JAVA_HOME%\bin。
4. 重新打开 cmd 再验证一次。

注意：改完环境变量后，已经开着的 IDEA 和 cmd 都要关掉重开，否则读不到新配置。这个坑我踩过，改了半天还以为没生效。

1.2 Maven 下载：官网文件与“无中文、无空格”的路径原则

Maven 是一个构建工具，简单理解就是“帮你管理 jar 包和编译打包流程的管家”。Java 项目需要的第三方库（比如日志框架、数据库驱动）全部由 Maven 帮你下载和管理，你不用再手动去复制 jar 包进项目了。

去 Maven 官网（maven.apache.org），点击 Download，下载apache-maven-3.9.x-bin.zip或 tar.gz 文件。Windows 选 zip，Mac 和 Linux 选 tar.gz。我不建议通过 IDE 内部下载 Maven，独立安装能让你搞清楚它在系统中的位置，排查问题也方便。

下载后解压，注意两个原则：

• 路径不能有中文，比如D:\开发工具\maven这种路径在后续构建时容易出诡异编码问题。
• 路径中最好不要有空格，比如C:\Program Files\Apache\apache-maven这种虽然能用，但某些插件和命令行工具对空格敏感，新手调试起来很痛苦。

我自己的习惯是放在D:\tools\apache-maven-3.9.9，简洁干净。

解压后配置环境变量，方式和 JDK 一样：

1. 新建系统变量 MAVEN_HOME，值为 Maven 解压目录。
2. 编辑 Path，新增%MAVEN_HOME%\bin。
3. 重新开 cmd，输入：

mvn -v

看到Apache Maven 3.9.9和 Java 版本信息就说明配置成功。mvn -v 是验证 Maven 环境是否正常的黄金命令，以后所有 Maven 问题的排查第一步都是它。

1.3 settings.xml 是新手第一个必改文件：本地仓库与阿里云镜像

Maven 下载的所有 jar 包都存在一个叫“本地仓库”的文件夹里，默认位置是C:\Users\你的用户名\.m2\repository。用默认位置不是不行，但 C 盘空间紧张，而且如果你想以后找 jar 包在哪、清理缓存，放在 D 盘更舒服。

Maven 的全局配置文件叫settings.xml，位于 Maven 安装目录的conf文件夹下。用文本编辑器（Notepad++、VS Code 都可以）打开，你会看到一堆注释。需要改动两处：

第一处是本地仓库路径。在<settings>标签内找到被注释掉的<localRepository>节点，改成你自己的目录：

<localRepository>D:/tools/maven-repo</localRepository>

注意 Windows 下写盘符路径用的是正斜杠D:/，虽然反斜杠也行，但正斜杠在所有系统里都兼容，不会因为转义字符踩坑。

第二处是镜像。这一步是国内用户的救命配置：如果不配镜像，Maven 默认从中央仓库 repo.maven.apache.org 下载依赖，这个源在国外的速度非常不稳定，经常下载到一半超时，然后你的项目就一直报红。我把阿里云镜像配置直接贴出来：

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

把这段加在<settings>标签内部，保存即可。mirrorOf 的值我建议写central，意思是只拦截中央仓库的请求。不要写*，因为如果你以后公司内部有自己的私服，*会把私服请求也劫持掉。

配置完成后，你在 IDEA 里新建的 Maven 项目也会读取这个 settings.xml。验证方式是在 cmd 里跑一句：

mvn help:system

这个命令会下载一些基础插件，如果速度快且没有报错，说明镜像配置生效了。

2. 在 IDEA 2025.3.3 里新建项目的每一步操作

环境准备好之后，打开 IDEA。这一步的界面和 2020 年左右的老教程差别最大，别拿老截图对照，以你屏幕上实际显示为准。

2.1 New Project 向导中 Build System 的选择

进入 IDEA 欢迎界面后，点击New Project，进入新建向导。2025.3.3 的向导和早期版本明显不同：它不再要求你先选 Maven 还是 Gradle 再填名字，而是统一在右侧配置。

关键的几个选项：

• Name：项目名称，比如maven-demo。
• Location：项目存放位置，这个无所谓，但路径同样别带中文。
• Language：选 Java。
• Build system：这一项最关键，下拉选择Maven。
• JDK：下拉选择你安装的 JDK 21。如果下拉框里是空的，点击旁边的Add JDK...按钮，手动定位到 JDK 安装目录，IDEA 会自动识别。

有些人可能会问：IDEA 里不选 Maven，直接创建一个普通 Java 项目也能跑，为什么非要用 Maven？区别在于：普通项目的 jar 包管理全靠手动，你下载一个 jar 放进 lib 目录，换一台电脑就失效；Maven 项目只需要在 pom.xml 里写一行依赖坐标，Maven 自动下载、自动管理版本，团队协作时别人拉你的代码也不用到处找 jar 包。

如果你用的是社区版，这里同样有 Build system 选项，社区版对 Maven 的支持是完整的，放心使用。

2.2 正确填写坐标：Project name、GroupId、ArtifactId

很多教程在这里直接跳过了，导致新手创建完项目一脸懵：这个com.example是什么？为什么包名这么奇怪？

Maven 项目有“坐标”的概念，用来唯一标识一个项目。三个核心字段：

• GroupId：组织标识，通常是你公司域名的反写，比如com.company、org.example。个人项目写com.example完全没问题。
• ArtifactId：项目标识，一般就是项目名，比如maven-demo。
• Version：版本号，默认1.0-SNAPSHOT。

在 2025.3.3 的新建向导里，Name 填完后 IDEA 会自动生成 ArtifactId，你只需要注意 GroupId 是否合理。如果界面上没看到 GroupId 选项，点开Advanced Settings之类的折叠区域就能找到。

这三个字段以后会变成你项目的“身份证”。pom.xml 里依赖别的项目时，就是用坐标来引用的；你自己写的东西以后想发布到仓库，也是用这套坐标。养成填好坐标的习惯，比随便起个名字重要得多。

2.3 项目生成后的界面，先认清楚三个面板

点击 Create 后，IDEA 会花几秒钟初始化项目。生成后的界面看起来东西很多，但新手只需要认清楚三个区域：

第一个是左侧的 Project 面板。你会看到项目结构：src/main/java、src/main/resources、src/test/java，以及项目根目录下的pom.xml文件。如果看到src/main/java下还有自动生成的包（就是你填的 GroupId 对应的包），这很正常。

第二个是右侧靠边的 Maven 工具窗口。IDEA 2025 系列里它默认在右侧竖排的图标栏里，图标是一个带字母 M 的圆形。点开之后能看到四个分类：

• Lifecycle：里面有一串命令，clean、validate、compile、test、package、install 等。
• Plugins：项目里用到的所有 Maven 插件。
• Dependencies：项目声明的所有依赖列表。

第三个是 IDEA 顶部或右侧的 Maven 刷新按钮。它是一个圆形循环箭头图标，鼠标悬停显示Reload All Maven Projects。以后你改了 pom.xml，点这个按钮重新加载依赖，这个动作的频率会比你想象得高。

到这里，一个“空的” Maven 项目就算建好了。接下来我们要理解 pom.xml，因为接下来所有配置都在它里面进行。

3. pom.xml 阅读课：Maven 的依赖管理到底是怎么运转的

创建完项目后，IDEA 会自动打开pom.xml。这是 Maven 项目的核心配置文件，也是新手最看不懂的文件。看不懂没关系，跟着拆一遍就懂了。

3.1 逐段拆解一个最小 pom.xml

默认生成的 pom.xml 精简后大概长这样：

<project xmlns="http://maven.apache.org/POM/4.0.0"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>maven-demo</artifactId> <version>1.0-SNAPSHOT</version> <properties> <maven.compiler.source>21</maven.compiler.source> <maven.compiler.target>21</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> </project>

逐个解释：

• modelVersion：固定写 4.0.0，这是 Maven 配置文件的格式版本，不用动。
• groupId、artifactId、version：就是你创建项目时填的坐标，告诉别人“我是谁”。
• properties：定义一些公共属性，避免在多个地方重复写版本号。
• maven.compiler.source和maven.compiler.target：指定编译用的 Java 版本。如果不写，Maven 默认按 JDK 1.5 的规则编译，你代码里用var关键字都会被判编译错误。设成 21 代表按 Java 21 语法标准编译。
• project.build.sourceEncoding：源文件编码，必须写成 UTF-8。不写的话，Windows 默认 GBK 编码，跨平台协作时中文注释直接乱码。

这一小节内容不算难，但它解释了为什么很多人“写代码明明没错，一构建就报 target 发行版错误”——就是上面那两个 compiler 版本设置没写。

3.2 手动加入第一个依赖：坐标从哪来、IDEA 如何自动导入

现在做一个实操：给项目加入 JUnit 5 测试框架。这是最经典的依赖示例。

在<properties>之后加一个<dependencies>节点：

<dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.11.3</version> <scope>test</scope> </dependency> </dependencies>

问题来了：这串<groupId>、<artifactId>、<version>从哪来的？答案是 mvnrepository.com。这个网站收录了几乎所有主流 Java 库的坐标信息，你在上面搜索 “junit”，找到对应版本，复制它的 Maven 坐标，粘贴到 pom.xml 即可。

粘贴后，IDEA 识别到 pom.xml 变化，会弹出一个气泡提示，让你点击Load Maven Changes或者类似按钮，点击后右侧 Dependencies 列表就会出现 junit-jupiter 以及它依赖的其他 jar 包。如果没有弹气泡，就手动点右侧的 Reload 按钮。

看到 Dependencies 里出现 jar 包名字，就说明 Maven 已经从（镜像后的）中央仓库下载成功了。依赖的 jar 包会缓存到之前配置的本地仓库里，你可以在D:/tools/maven-repo目录下看到它们的真实文件。

3.3 scope 与依赖传递：别只点 Add as Library

<scope>是依赖配置里很容易被忽略的字段。它决定这个依赖在什么阶段起作用。最常见的两个值：

• compile（默认）：主代码和测试代码都能用，打包时也要带上。比如你引入了 MySQL 驱动，就是在 compile 阶段用。
• test：只在测试代码里生效，比如 JUnit。主代码里如果用 JUnit 的类，编译直接报错，这其实是一种约束，防止你写出在线上运行却依赖测试框架的代码。

如果没有写 scope，默认就是 compile。新手期最简单的方式：从 mvnrepository.com 复制坐标时，如果人家写明了 scope，就一起复制；没写明就默认不加。

还有一个概念叫“依赖传递”。你引入了一个库，它内部又依赖别的库，Maven 会把这些间接依赖自动拉进来，不用你在 pom.xml 里一个个声明。比如引入spring-boot-starter-web后，你会看到 Dependencies 列表里多出几十个 jar，那些都是它的传递依赖。这就是为什么 Maven 能“一行依赖带一整套框架”。

在这里顺便提一句：网上有些教程教你右键 jar 包选Add as Library，或者手动把 jar 复制进 lib 目录。这种操作本质上绕过了 Maven 的管理体系，短期能跑，但项目依赖一多就会乱成一锅粥。尽量改掉这个习惯，所有依赖都通过 pom.xml 声明，才是正路。

4. 写代码、跑起来：从 main 方法到 Maven 生命周期

配置写得再多，最终要的是项目能跑。这一节用一个最简单的例子，把整个编译、测试、打包流程过一遍。

4.1 新建 Main 类和 JUnit 测试类

在src/main/java/com/example/目录下（包名看你自己的 GroupId），新建一个 Java 类Main.java：

package com.example; public class Main { public static void main(String[] args) { System.out.println("Hello Maven!"); } }

然后在src/test/java/com/example/目录下新建测试类MainTest.java：

package com.example; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.assertEquals; public class MainTest { @Test void testAddition() { int sum = 1 + 1; assertEquals(2, sum); } }

注意src/test/java目录默认已经存在，如果没有就手动创建。这是 Maven 约定的目录结构：主代码放src/main/java，测试代码放src/test/java。不要自己乱改目录，约定优于配置是 Maven 的核心哲学。

4.2 用 IDEA 的 Maven 工具窗口执行 clean、package、install

很多人习惯直接在 Main 类上右键选Run 'Main.main()'，这样当然能运行，但我想趁机把 Maven 的构建流程讲清楚，因为你以后接触 Spring Boot 项目、部署项目时，靠的都是 Maven 构建命令而不是 IDE 的运行按钮。

打开右侧 Maven 工具窗口，展开 Lifecycle，你会看到一串命令。挑几个核心的：

命令	作用	类比
clean	删除 target 目录（编译产物）	大扫除，把旧东西清掉
compile	编译主代码，输出到 target/classes	把源码变成 class 文件
test	运行测试代码，输出测试报告	自动跑一遍测试
package	测试通过后打包，生成 jar/war	把项目打包成可交付的制品
install	打包并安装到本地仓库	把制品放进“本地货架”供其他项目引用

先双击clean，再双击package，观察 IDEA 底部的 Build 窗口。你会看到日志一行行滚动，类似：

[INFO] --- maven-compiler-plugin:3.13.0:compile ... [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] Building jar: D:\projects\maven-demo\target\maven-demo-1.0-SNAPSHOT.jar

Tests run: 1表示 JUnit 测试执行了并全部通过，Building jar表示 jar 包已经生成。到这一步，你已经完整走了一遍 Maven 的构建生命周期。

打开target目录，你可以看到classes文件夹（编译后的 class 文件）、maven-demo-1.0-SNAPSHOT.jar（打包产物）。

这里有个非常重要的细节：这个 jar 直接运行会报错。

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

错误信息是“no main manifest attribute”。原因是：基础的 Maven jar 打包插件（maven-jar-plugin）不会自动在 MANIFEST.MF 里指定启动类，这个 jar 只能作为库被其他项目引用，不能直接双击运行。如果你要生成“可双击运行”的 jar，需要配置maven-shade-plugin或使用 Spring Boot 的打包插件把启动类写进清单。对于基础项目，在 IDEA 里右键 Main 类运行就足够了，不要被这个错误吓到。

4.3 解决控制台中文乱码：编码问题一次配好

运行 Main 类或执行 Maven 命令时，控制台如果出现???或锟斤拷之类的东西，说明编码不一致。

三个地方都要设置成 UTF-8：

第一处，IDEA 设置里的 File Encodings。路径是File -> Settings -> Editor -> File Encodings，把 Global Encoding、Project Encoding、Properties Files 三项全部设为 UTF-8。

第二处，pom.xml 里已经有project.build.sourceEncoding，前面步骤已经配好，可以保护 Maven 编译时源文件编码不跑偏。

第三处，如果还是乱码，改 IDEA 的启动配置。Help -> Edit Custom VM Options，在文件末尾加一行：

-Dfile.encoding=UTF-8

保存后重启 IDEA。这一步属于 IDE 层面的兜底方案，实测能解决九成以上的控制台乱码。

5. 新手最容易踩的坑：依赖报红、下载超时、target 目录消失全排查

跑通第一个项目之后，你大概率会开始动手加自己的依赖，接数据库、接第三方 SDK，然后各种问题就冒出来了。这些坑我当年全踩过，统一写在这里当作排查手册。

5.1 依赖标红、IDEA 一直加载：先看本地仓库再谈网络

项目 pom.xml 里刚写完一个依赖，IDEA 左边的红字提示报错，或者右下角一直显示 “Resolving Maven dependencies...”。这是新手提问率最高的问题。

我的排查顺序是：

1. 看 Maven 设置里的本地仓库路径是否正确。路径是Settings -> Build, Execution, Deployment -> Build Tools -> Maven，看 Local repository 这一项是否指向了你配置的目录。如果你的 settings.xml 在 D 盘，IDEA 默认读取C:\Users\用户名\.m2\settings.xml，两边不一致就会反复下载。

2. 去本地仓库目录找找对应 jar。比如你依赖的是org.junit.jupiter，就去D:/tools/maven-repo/org/junit/jupiter下面看。如果存在.lastUpdated后缀的文件，说明上次下载中断了，IDEA 不会自动重新下载，需要把这些.lastUpdated文件和对应空目录删除，然后点 Reload 按钮。

3. 删除后重新加载。在 IDEA 右侧 Maven 工具窗口点那个循环箭头图标，或者直接执行mvn clean test让 Maven 强制重新解析。

这个.lastUpdated文件机制让很多人困惑：明明网络没问题，为什么依赖一直下载不下来？因为 Maven 为了性能，会把下载失败的状态缓存起来，在超时窗口内不会重试。手动删掉这个文件是最好的触发重试的方式。

5.2 target 目录明明存在却看不见：文件类型过滤器的锅

有时候你明明执行了 package，打开资源管理器看到 target 目录就在那儿，但 IDEA 的 Project 面板里死活不显示。这个坑跟目录本身无关，是 IDEA 把 target 标记为了“排除目录”。

解决方式：点击 Project 面板右上角的齿轮图标，检查是否勾选了Hide Excluded Files，如果勾了就取消勾选，target 目录就会显示出来，颜色呈橙色。如果不小心勾了，不仅看不到 target，有些新手还会误以为打包失败，白白浪费时间重跑好几遍。

顺带一提，src/main/resources和src/test/resources这类目录如果没显示，大概率是 IDE 的文件树过滤器问题，右键项目根目录，选择Reload from Disk也能强制刷新。

5.3 Maven 官方仓库下载超时：镜像优先级和多个镜像的配置

即使配了阿里云镜像，偶尔还是会遇到某个依赖下载很慢，或者某个冷门库在阿里云镜像里不存在、必须回源到中央仓库的情况。这时候你可能想多加几个镜像。

但这里有个知识点：Maven 的 mirror 不是“负载均衡”，而是“优先命中”。在 settings.xml 里配置多个 mirror 时，Maven 只使用第一个匹配当前请求的 mirror，后面的会被忽略。如果你第一个 mirror 的 mirrorOf 写成了*，那后面配置的镜像永远不生效。

正确的多镜像配置方式有两种：

第一种，mirrorOf 指定范围。比如阿里云镜像覆盖central，华为云镜像覆盖central，其实效果一样，因为第二个 matching 镜像不会被用到。

第二种，通过 profile 配置 repository。在 settings.xml 里加：

<profiles> <profile> <id>nexus</id> <repositories> <repository> <id>aliyun-public</id> <url>https://maven.aliyun.com/repository/public</url> </repository> </repositories> </profile> </profiles> <activeProfiles> <activeProfile>nexus</activeProfile> </activeProfiles>

这样项目的依赖解析会走配置的 repository 列表，而 mirror 负责拦截中央仓库请求。这种方式更复杂，新手期其实用不着。我的建议是：先用阿里云 public 这一个镜像，覆盖绝大多数需求，遇到冷门库下载失败再临时把 mirrorOf 改成*或者针对单个项目配 repository。别在一开始就把镜像配成一堆，给自己增加排查难度。

讲到这里，基础项目的创建、配置、运行和排错链路基本完整了。我个人特别想强调的一点是：新手期不要急着把 Maven 命令行参数全背下来，先让项目在 IDEA 里稳定跑通一次，亲眼看到 Dependencies 列表里出现 jar 包、target 目录里出现打包产物，你就理解 Maven 的价值了。之后再去学哪些生命周期的组合使用、怎么配多模块项目，都会顺畅很多。如果你接下来要往 JavaWeb 方向走，无非是在 pom.xml 里加 Spring Boot 相关依赖，但这个基础工程的底子，就是你现在建好的这个 Maven 项目。