如果你刚装好 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 没配好。检查步骤右键“此电脑” - 属性 - 高级系统设置 - 环境变量。在系统变量里新建 JAVA_HOME值为 JDK 安装目录比如C:\Program Files\Eclipse Adoptium\jdk-21.0.2。编辑 Path 变量新增%JAVA_HOME%\bin。重新打开 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 选 zipMac 和 Linux 选 tar.gz。我不建议通过 IDE 内部下载 Maven独立安装能让你搞清楚它在系统中的位置排查问题也方便。下载后解压注意两个原则路径不能有中文比如D:\开发工具\maven这种路径在后续构建时容易出诡异编码问题。路径中最好不要有空格比如C:\Program Files\Apache\apache-maven这种虽然能用但某些插件和命令行工具对空格敏感新手调试起来很痛苦。我自己的习惯是放在D:\tools\apache-maven-3.9.9简洁干净。解压后配置环境变量方式和 JDK 一样新建系统变量 MAVEN_HOME值为 Maven 解压目录。编辑 Path新增%MAVEN_HOME%\bin。重新开 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节点改成你自己的目录localRepositoryD:/tools/maven-repo/localRepository注意 Windows 下写盘符路径用的是正斜杠D:/虽然反斜杠也行但正斜杠在所有系统里都兼容不会因为转义字符踩坑。第二处是镜像。这一步是国内用户的救命配置如果不配镜像Maven 默认从中央仓库 repo.maven.apache.org 下载依赖这个源在国外的速度非常不稳定经常下载到一半超时然后你的项目就一直报红。我把阿里云镜像配置直接贴出来mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://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 xmlnshttp://maven.apache.org/POM/4.0.0 modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmaven-demo/artifactId version1.0-SNAPSHOT/version properties maven.compiler.source21/maven.compiler.source maven.compiler.target21/maven.compiler.target project.build.sourceEncodingUTF-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 groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version5.11.3/version scopetest/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 Libraryscope是依赖配置里很容易被忽略的字段。它决定这个依赖在什么阶段起作用。最常见的两个值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.javapackage com.example; public class Main { public static void main(String[] args) { System.out.println(Hello Maven!); } }然后在src/test/java/com/example/目录下新建测试类MainTest.javapackage 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.jarTests 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.encodingUTF-8保存后重启 IDEA。这一步属于 IDE 层面的兜底方案实测能解决九成以上的控制台乱码。5. 新手最容易踩的坑依赖报红、下载超时、target 目录消失全排查跑通第一个项目之后你大概率会开始动手加自己的依赖接数据库、接第三方 SDK然后各种问题就冒出来了。这些坑我当年全踩过统一写在这里当作排查手册。5.1 依赖标红、IDEA 一直加载先看本地仓库再谈网络项目 pom.xml 里刚写完一个依赖IDEA 左边的红字提示报错或者右下角一直显示 “Resolving Maven dependencies...”。这是新手提问率最高的问题。我的排查顺序是看 Maven 设置里的本地仓库路径是否正确。路径是Settings - Build, Execution, Deployment - Build Tools - Maven看 Local repository 这一项是否指向了你配置的目录。如果你的 settings.xml 在 D 盘IDEA 默认读取C:\Users\用户名\.m2\settings.xml两边不一致就会反复下载。去本地仓库目录找找对应 jar。比如你依赖的是org.junit.jupiter就去D:/tools/maven-repo/org/junit/jupiter下面看。如果存在.lastUpdated后缀的文件说明上次下载中断了IDEA 不会自动重新下载需要把这些.lastUpdated文件和对应空目录删除然后点 Reload 按钮。删除后重新加载。在 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 idnexus/id repositories repository idaliyun-public/id urlhttps://maven.aliyun.com/repository/public/url /repository /repositories /profile /profiles activeProfiles activeProfilenexus/activeProfile /activeProfiles这样项目的依赖解析会走配置的 repository 列表而 mirror 负责拦截中央仓库请求。这种方式更复杂新手期其实用不着。我的建议是先用阿里云 public 这一个镜像覆盖绝大多数需求遇到冷门库下载失败再临时把 mirrorOf 改成*或者针对单个项目配 repository。别在一开始就把镜像配成一堆给自己增加排查难度。讲到这里基础项目的创建、配置、运行和排错链路基本完整了。我个人特别想强调的一点是新手期不要急着把 Maven 命令行参数全背下来先让项目在 IDEA 里稳定跑通一次亲眼看到 Dependencies 列表里出现 jar 包、target 目录里出现打包产物你就理解 Maven 的价值了。之后再去学哪些生命周期的组合使用、怎么配多模块项目都会顺畅很多。如果你接下来要往 JavaWeb 方向走无非是在 pom.xml 里加 Spring Boot 相关依赖但这个基础工程的底子就是你现在建好的这个 Maven 项目。