写这篇教程的念头源于我带一个刚入职的同事。他计算机专业毕业JDK 装好了IDEA 2025.3.3 装好了但面对一个 Maven 项目他不知道点哪里也不知道 pom.xml 是干嘛的。他问得最多的一句话是Maven 到底在干嘛于是我从零给他搭了一个可以跑的 Maven 项目每一步都解释为什么这么做。今天把这些内容整理成这篇超详细的新手教程目标只有一个跟着做完你就能用 IDEA 2025.3.3 创建、运行、打包一个最基础的 Maven 项目并且以后看到陌生项目时能自己判断它缺了哪个环节。1. Maven 在项目里到底扮演什么角色1.1 Maven 是干嘛的一个开箱即用的依赖管家很多人第一次接触 Maven是从报错开始的。jar 包下载不完整、IDEA 里依赖红线、本地仓库找不着……然后就开始在网上搜maven 依赖报错。但你得先理解它解决的问题。设想一个没有 Maven 的 Java 项目你要做什么去网上下载一个 commons-io-2.15.0.jar把它拷进项目里的 lib 目录然后右键 Add as Library。如果你的代码里还要用 JSON又得去下载 jackson-databind.jar然后你发现 jackson-databind 还依赖 jackson-core 和 jackson-annotations你要手动把这三个 jar 全部找齐还得保证版本互相兼容。这就好比你想点一盘宫保鸡丁外卖结果外卖平台不干了你得自己种花生、养鸡、再炒菜。Maven 就是来解决这个问题的。你把需求写在 pom.xml 里它自动去中央仓库把 jar 包下载到本地仓库并且连带下载你需要的依赖的依赖。你再也不用手动管理 jar 文件只需要管理一份配置清单。这份清单就是 pom.xml它在项目根目录下是所有 Maven 项目的核心。除了管理依赖Maven 还统一了构建流程。一个 Java 项目从源代码到可运行产物要经过编译、测试、打包等步骤Maven 把这些步骤定义成了标准生命周期。你在命令行敲 mvn clean package它就会按顺序帮你清理旧的构建产物、编译代码、跑测试、打成可执行的 jar 包。IDEA 里的 Maven 面板本质上就是帮你可视化地执行这些命令不用你记全命令。1.2 为什么用 IDEA 2025.3.3 来创建 Maven 项目市面上讲 Maven 的教程很多环境一会儿是命令行、一会儿是 Eclipse、一会儿是 VSCode新手很容易被搞晕。这篇教程统一用 IDEA 2025.3.3 作为操作环境原因是它内置了 Maven 支持你不需要额外安装插件新建项目时就有 Maven 类型可选。IDEA 会自动解析 pom.xml、下载依赖、编译代码并且把 Maven 面板中的命令封装成图形按钮。你用 IDEA 创建 Maven 项目本质上是让它调用 Maven 的工作目录结构、配置文件模板生成一个符合规范的工程。2025.3.3 这个版本的 New Project 向导更直观默认的 JDK 检测、SDK 选择也比旧版清晰不少。另外它对项目的索引速度、依赖导入提示都有优化新手在图形界面上就能看到正在导入 Maven 项目这样的状态心里不慌。1.3 这篇教程带你把哪些事串起来我希望你把 Maven 看成一个完整链路而不是零散知识点。这个链路的起点是你本机的 JDK 和 Maven 安装中间是 IDEA 里配置的 Maven home path、settings.xml、本地仓库然后是新建一个项目、在 pom.xml 里声明依赖最后是让项目里出现一个能跑起来的类再把它打包成 jar。每一环都可能是出问题的地方。有人 JDK 没配好IDEA 就一直报无效的源发行版有人 Maven 下载慢是因为没有配置阿里云仓库有人创建项目时选错了模板生成出来的目录结构根本看不懂。这些坑你都会在这篇教程里正面遇到我会告诉你为什么会出现以及怎么解决。2. 动手前的环境准备JDK 和 Maven 安装配置2.1 先装 JDK并把它写进环境变量不管你用什么集成开发环境JDK 永远是第一块地基。Maven 本身是一个用 Java 写的工具它运行的前提也是机子里有 JDK。所以别跳过这一步直接装环境变量。我推荐 JDK 17 或 JDK 21这两个版本是 LTS 长期支持版和 IDEA 2025.3.3、以及 Maven 3.9.x 配合都很稳定。Windows 用户去 Oracle 官网或者国内镜像下载对应平台的安装包安装完以后关键一步是配置系统环境变量 JAVA_HOME把它指向 JDK 的安装目录比如 C:\Program Files\Java\jdk-17。然后在系统变量的 Path 中新增一条%JAVA_HOME%\bin。这样做的目的是让命令行在任何目录下都能找到 java 和 javac。macOS 用户的路径一般是 /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home或者你直接用一个版本管理工具比如 brew install openjdk17。配置完打开终端输入java -version看到类似 java version 17 的输出就说明 JDK 没问题。这里有个经常坑到新手的细节系统里如果装过多个 JDK环境变量 JAVA_HOME 指向的是旧版本命令行和 IDEA 里识别到的 Java 版本就会不一致。最简单的方法是先卸载不用的旧版本或者在环境变量里精确指定你想要的版本路径不要用通配符也不要用别人复制给你的默认路径。2.2 下载 Maven 并配置环境变量Maven 的官方网站提供两个版本下载Binary zip archive 和 Source zip archive。新手直接下载 Binary zip archive 就好Source 是源码包你不需要自己编译 Maven。当前稳定版本一般以 3.9.x 开头适配 JDK 8 以上。网上一搜还会看到 apache-maven-3.6.1 这种老版本那是早期教程流传下来的老项目会要求 3.6.1但新项目真心建议用 3.9.x它在 JDK 17 以上的兼容性更好插件解析速度也快。下载完成后解压到一个没有空格的路径比如 D:\apache-maven-3.9.6 或者 /opt/apache-maven-3.9.6。然后配置环境变量 MAVEN_HOME指向 Maven 的解压目录再把%MAVEN_HOME%\bin加到 Path 里。macOS 用户编辑 ~/.zshrc添加 export MAVEN_HOME/opt/apache-maven-3.9.6 和 export PATH$MAVEN_HOME/bin:$PATH然后 source ~/.zshrc。配完以后打开新终端执行mvn -v正常输出会包含 Apache Maven 版本号以及 Java 版本。如果提示无法识别 mvn说明 Path 没配对或者终端没有重启。这里有一个小经验Windows 系统改完环境变量后必须重新打开命令行窗口旧的窗口不会自动刷新环境变量。2.3 配置 settings.xml 和阿里云镜像把下载速度提上来Maven 下载依赖默认访问的是中央仓库 repo.maven.apache.org服务器在海外国内网络环境下经常很慢甚至直接超时。解决办法是配置一个国内镜像仓库阿里云是目前最稳的选择。Maven 的配置文件叫 settings.xml它有两个层级一个是 Maven 安装目录下的 conf/settings.xml影响所有用户另一个是用户目录下的 ~/.m2/settings.xml只影响当前用户。如果你只有一个机子、一个账号我建议直接改用户目录下的这个文件避免动安装目录的配置。在 ~/.m2 目录下打开 settings.xml找到mirrors节点添加以下内容mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror这段配置的作用是所有从中央仓库拉取的依赖请求都转发到阿里云。mirrorOf 写 central 表示只对中央仓库生效不会影响你自己搭建的私服。配好之后你可以跑一个简单的命令验证比如 mvn help:system看依赖下载日志里 URL 是否变成了 aliyun 开头的地址。本地仓库默认在 ~/.m2/repositoryMaven 下载的所有 jar 包都会存放在这个目录。网上的热搜词里有个问题我有两个 maven 的本地仓库 repository怎么合并这种情况大多是因为早期用过 IDEA 自带的 Maven后来又在命令行装了一个新的 Maven两个实例分别建立了自己的本地仓库一个在 C 盘用户目录一个在 D 盘某个位置。合并思路很简单在 settings.xml 里把localRepository统一指向同一个目录然后在 IDEA 的 Maven 设置里也指向这一个目录。旧仓库里已经存在的 jar 包可以拷贝到新仓库但如果版本混乱我更建议直接让 Maven 重新下载——反正有了阿里云镜像重新下载也就几分钟的事。3. 在 IDEA 2025.3.3 里创建第一个 Maven 项目3.1 先配置全局 Maven而不是直接新建项目新手最常见的操作是打开 IDEA直接 File → New → Project然后选 Maven看到模板就下一步结果项目建出来一堆看不懂的文件。其实你少做了一个很重要的动作先把 IDEA 的 Maven 配置指向你自己安装的那个 Maven。打开 File → Settings → Build, Execution, Deployment → Build Tools → Maven你会看到 Maven home path。默认情况下它可能指向 IDEA 自带的 Maven我建议手动选择你刚才安装的 Maven 目录比如 D:\apache-maven-3.9.6。这样 IDEA 里的 Maven 和命令行里的 Maven 是同一个版本行为一致排查问题也方便。紧接着下面的 User settings file 要选择你刚才配置过阿里云镜像的 settings.xml即 ~/.m2/settings.xml。选完之后Local repository 会自动读取 settings.xml 里配置的本地仓库路径不需要手填。这一套配置做完点 OK 保存。这一步的意义在于让 IDEA 认识和命令行完全一样的 Maven 环境避免出现IDEA 里能下载依赖命令行却报错这一类奇葩问题。网上搜ide 怎么配置 jdk 和 maven大部分人卡住就是因为只配了其中一个没有把全局配置和项目运行时的 JDK、Maven 统一起来。3.2 用 New Project 向导创建项目配置好全局 Maven 后开始创建项目。在 IDEA 2025.3.3 里选择 File → New → Project左侧选择 New Project然后在最上面的列表里选 Maven。如果你的界面版本不太一样找带有 Maven 字样的 Generator 选项。这里特别提醒不要在新建项目那里勾选 Create from archetype也不选 maven-archetype-quickstart 这类模板。对新手来说archetype 创建出来的项目带了一堆预设文件和过时的目录结构反而容易让你困惑。我们只需要一个干净的空 Maven 项目。填写的字段有三个核心GroupId、ArtifactId 和 Version。GroupId 一般是公司的域名反写比如 com.exampleArtifactId 是项目名比如 demo-projectVersion 默认 1.0-SNAPSHOT代表快照版本。这三项合起来就是 Maven 坐标用来唯一标识一个项目。填完之后点击 CreateIDEA 会开始构建项目索引。第一次创建时它会在后台自动下载 Maven 的一系列插件和依赖整个过程可能需要几分钟。你可以看右下角的进度条首次无论多慢都正常因为本地仓库是空的。如果你刚才配置了阿里云镜像这一步会快很多。3.3 认识生成出来的目录结构项目创建好后src 目录下会有两个子目录src/main/java 用来放项目源代码src/test/java 用来放单元测试代码src/main/resources 用来放配置文件比如 application.yml、log4j 配置等。现在的 IDEA 版本默认不一定生成 resources 目录没有就手动创建反正 Maven 只看目录名不看是谁建的。项目根目录下的 pom.xml 是整个项目的核心。它至少包含 modelVersion、groupId、artifactId、version 这些基本节点还有一个dependencies节点后续你要引入什么 jar 包都是在里面加dependency。IDEA 界面左侧会有一个 Maven 面板里面展开 Lifecycle能看到 clean、validate、compile、test、package、verify、install、deploy 这些命令按钮。这个面板相当于图形化的命令行双击任何一个IDEA 就会执行对应的 Maven 命令。另外你会看到 target 目录它是构建输出目录编译后的 class 文件、打出来的 jar 包都会放在这里。target 目录在我刚开始学习时很容易被误改其实它每次构建都会自动刷新你完全不用手动往里放东西。4. 让项目真正可运行写代码、配置 pom、打 jar 包4.1 写一个最简单的类先跑起来再说创建完项目先不急着配一堆插件第一步是让 IDE 里有个可以点运行按钮的 Java 类。在 src/main/java 下面新建一个包比如 cn.demo然后创建一个 DemoApplication.java内容是package cn.demo; public class DemoApplication { public static void main(String[] args) { System.out.println(Hello Maven, running from IDEA 2025.3.3); } }写完以后在代码里右键选择 Run DemoApplication.main()IDEA 会临时为你编译这个文件然后在底部控制台输出 Hello Maven。到这里你已经在 IDEA 里成功运行了一个 Java 程序但严格来说这个程序还不是通过 Maven 构建的它只是 IDEA 帮你编译的。要让它真正属于 Maven 项目你需要通过 Maven 的生命周期命令来处理它。IDEA 里的 Maven 面板双击 compile或者打开终端执行 mvn compile你就发现 target/classes 目录下生成了 .class 文件。这时候再运行 main 方法跑的就是 Maven 编译出的字节码。这个区别新手可能感觉不大但后面做多模块项目、打包部署时一切都要依赖 Maven 的构建步骤。4.2 在 pom.xml 里正确定义 Java 编译版本运行虽然通了但你先别急着高兴。如果什么都不改直接执行 mvn package报错概率很高最常见的错误是 invalid source release: 17意思是 Maven 默认用的编译级别和你当前 SDK 不匹配。Maven 本身的默认编译级别是 Java 5你要显式告诉它用哪个版本的语法。推荐的做法是在 pom.xml 的 properties 节点里指定properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /propertiessource 表示源码使用的 Java 版本target 表示编译产物的字节码版本encoding 设置为 UTF-8 防止中文乱码。你如果装的是 JDK 21就把两个值都改成 21。这个配置对应到 IDEA 里就是 Settings → Build Tools → Maven → Runner 里的 JRE 设置两边的版本最好保持一致。有时候你会看到网上教程让你在 build → plugins 里配置 maven-compiler-plugin 的 source 和 target效果一样但用 properties 更简洁能少写一大段 XML。4.3 三种运行方式对比直接 Run、mvn exec、打包再跑很多初学者只会在 IDEA 里右键运行 main 方法换个环境就不知道怎么跑了。我把三种方式全列出来你最好都试一遍。第一种是右键直接运行IDEA 会自己调用 Maven 编译当前模块然后执行 main 方法适合开发调试阶段。第二种是在 pom.xml 里配置 exec-maven-plugin这样可以在命令行用 mvn exec:java 运行程序。第三种是把项目打成 jar 包再用 java -jar 执行这是最接近生产环境的方式也是你以后部署项目的基本形态。要让 mvn exec:java 能跑需要在 build 节点里添加插件并且指定 mainClass 为类的全限定名build plugins plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.2.0/version configuration mainClasscn.demo.DemoApplication/mainClass /configuration /plugin /plugins /build配置完之后在终端执行mvn exec:java -q你会看到 main 方法里的打印语句输出。这种方式好处是不需要依赖 IDEA纯命令行环境也能跑 Java 程序而且会用 Maven 管理的依赖来编译不会出现IDEA 能跑命令行跑不了的尴尬。至于第三种打包运行你要注意一个细节默认的 mvn package 打出来的 jar 包是瘦包里面不含任何第三方依赖。如果你的程序只是打印一句话那 java -jar 没问题但如果代码里用了别人的库直接跑会报 ClassNotFoundException。解决方式是加 maven-shade-plugin 把依赖打进去或者用 spring-boot-maven-plugin 自带的 repackage。新手阶段理解了要不要把依赖打进 jar这个区别就算真正迈过 Maven 的门槛了。我直接用一段可复制的 pom 来演示最常规的做法build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-jar-plugin/artifactId version3.4.1/version configuration archive manifest mainClasscn.demo.DemoApplication/mainClass /manifest /archive /configuration /plugin /plugins /build这一段配置往 jar 包的 MANIFEST 文件中写入 Main-Class 属性使 java -jar 能得到正确的启动类。4.4 完整的命令行构建流程在项目根目录依次执行这几个命令你会清晰看到 Maven 生命周期每一阶段的产出mvn clean mvn compile mvn test mvn package mvn installclean 删除 target 目录compile 编译源代码test 运行 src/test/java 下的单元测试package 把编译产物打包成 jarinstall 把 jar 安装到本地仓库供其他本地项目引用。Maven 生命周期的设计是阶段化的执行 package 时前面的 compile 和 test 会自动执行不需要手动一条条敲。这也是 Maven 和普通脚本最大的区别它不是一条命令干一件事而是一套有顺序的构建管线。新手第一次执行 mvn package可能会看到下载大量插件比如 maven-resources-plugin、maven-surefire-plugin 等这些是 Maven 构建的基本零件。等待时间取决于网络速度和是否配置了镜像。执行完成后进 target 目录找到 demo-project-1.0-SNAPSHOT.jar这就是你的构建成果。5. 新手最容易踩的坑和排查技巧5.1 依赖下载失败或 IDEA 里依赖全部飘红依赖飘红是 Maven 新手的第一大噩梦。右键项目 → Maven → Reload Project这是最常用的解决办法相当于让 IDEA 重新解析一次 pom.xml并把缺失的依赖重新下载。如果 Reload 之后还是红你就要怀疑是不是下载过程被中断了本地仓库里残留了 .lastUpdated 结尾的坏文件。这种文件导致的问题是Maven 发现本地已经有这条依赖的痕迹就不再去远端重新下载了哪怕那个文件是个坏的。解决办法是删掉本地仓库里对应的目录再执行 mvn -U 强制更新。-U 的含义是强制检查远程仓库安全有效但别过度使用因为每次都强制更新会拖慢构建速度。如果错误信息里面有 407 或者 Proxy 相关字样说明你的网络代理设置影响了 Maven。IDE 里一般会在 Settings → HTTP Proxy 里有自动检测配置Maven 本身也可能会读取系统的代理环境变量。遇到这种情况最简单的做法是检查你的网络环境是否直接可用然后重新导入项目。日志是排查的关键命令行执行mvn -X可以输出调试级别的日志虽然信息量很大但耐心找一下就能定位大概是哪一步卡住了。5.2 明明配了 Maven命令行却运行不了你可能会遇到IDEA 里面 Maven 项目一切正常但打开终端执行 mvn 却提示 Not recognized。因为你只在 IDEA 的 Settings 里配置了 Maven 路径没有配置系统环境变量。IDEA 的配置和操作系统的 PATH 是两回事IDEA 能找到 mvn.cmd不代表操作系统能找到。反过来也有一种情况终端里 mvn -v 正常但 IDEA 里 Maven 面板报错说找不到 Maven home。这时回到 Settings → Build Tools → Maven把 Maven home path 指定到你安装的目录不要用 IDEA bundled然后再确认 JDK for importer 的版本选你需要的 LTS 版本。这一块在热搜词ide 怎么配置 jdk 和 maven里反复出现根本原因就在这里IDEA 的 Maven 配置、项目 SDK、命令行 JDK 三者是独立设置的必须让它们版本一致。5.3 两个本地仓库怎么合并谁占了我磁盘空间很多人装完 Maven 后会发现磁盘被占用了好几个 G就是因为存在多套本地仓库。早期你用 IDEA 自带的 Maven 在 C 盘建了一个 repository后来自己下载了 Maven又在 D 盘配置了另一个 repository。两个仓库各自存了一份依赖白白浪费空间。处理方式分两步。第一步统一本地仓库路径。在 ~/.m2/settings.xml 里指定localRepository为你实际想用的那个目录比如 D:\m2\repository然后 IDEA 设置里也指向同一个路径。第二步多余的旧仓库直接删除或把未下载完的坏目录清理掉。旧仓库里已有的 jar 包理论上可以直接拷贝到新仓库但这样容易带过来损坏的缓存、半截下载的文件远不如删掉让它重新下载干净。我处理过很多同事的电脑最后都只保留一个仓库省下的空间非常可观。5.4 关于maven 仓库网页版入口浏览器怎么找依赖坐标搜索热词里有maven 仓库网页版入口新手确实很容易和本地仓库搞混。这里说的网页版入口通常指两个地方一个是 mvnrepository.com它提供按关键字搜索 jar 包坐标你搜 gson它会列出所有版本点进去就能复制依赖 XML另一个是中央仓库的官方网站 repo.maven.apache.org属于权威源但没有前者方便检索。实际开发中你并不需要记住每个 jar 包的 GroupId 和 ArtifactId只需要能看懂坐标结构。一个依赖由组名、构件名、版本号三部分组成在 pom.xml 里声明一次Maven 就会从仓库拉取。比如dependency groupIdcom.google.code.gson/groupId artifactIdgson/artifactId version2.10.1/version /dependency把这段加到 dependencies 节点下等待依赖下载完成后代码里就能 import com.google.gson.Gson 了。搜索引擎给出的坐标一般都很准但注意版本的兼容性较新版本不一定和你当前的 JDK、框架匹配尽量选稳定版本。5.5 顺手记住几个关键快捷键和面板位置最后再分享几个我实际用下来能明显避免重复操作的窗口位置。文件菜单里的 Settings 或者 Preferences常用来配置全局 Maven。Maven 工具窗口一般在右侧边栏里面除了 Lifecycle还有 Dependencies 列表能看到整个项目当前的依赖树。假如你想检查某个 jar 为什么被引入点 Dependency Analyzer 或者依赖树就能看到依赖链路。IDEA 右下角会定期提示 Maven 项目需要导入或重新加载看到这个提示就点一下别无视这是防止依赖状态和 pom.xml 不同步最简单有效的方式。回顾整个流程我发现新手在 Maven 上遇到的大多数问题归根到底是对三个位置没区分清楚Maven 的安装目录、settings.xml 配置文件、本地仓库位置。安装目录决定 Maven 自身版本settings.xml 决定镜像和仓库策略本地仓库才是真正存放 jar 的地方。把这三点理顺之后无论换到哪个环境、哪个项目你都有一套清晰的心智模型再遇到问题就知道该检查哪一块。我自己刚流行起来的那段时间也踩过坑机器上装了三个 JDKIDEA 的 Runner 指向了老版本项目 pom 配的 source 却是 17每次编译报错都要排查好久。后来我养成一个固定习惯先命令行 java -version 确认 JDK再 mvn -v 确认 Maven最后才打开 IDEA 配项目。每次配新机子都按这个顺序基本不会再出现开发工具能用、命令行不能跑的怪事。创建一个基础的 Maven 项目并不神秘只要理解了依赖和构建这两条主线后面学 Spring Boot、多模块工程、私服上传都是水到渠成的事。