很多新手拿到 IDEA 2025.3.3 之后第一反应是“我是不是装了个假 IDEA”——新建项目模板一堆Maven 却不知道在哪里配置好不容易点完“Next”项目创建出来连src目录都没有跑一个 main 方法还报一堆依赖错误。这些我全都经历过。这篇教程我完全按新手视角来写从 Maven 到底是什么、为什么要配阿里云仓库到 IDEA 2025.3.3 里一步步创建并运行一个基础 Maven 项目全程带截图级描述和踩坑记录。文中所有关键步骤都可以直接照着操作复现不需要你有任何 Maven 基础。1. 先搞清楚 Maven 在项目里的角色1.1 Maven 是干嘛的我的通俗解释很多人把 Maven 想得太玄乎。拿生活里最简单的例子类比你以前写 Java 要自己上网搜 jar 包下载下来放到lib目录不同版本的 jar 还会互相打架换台电脑就要重新折腾一遍。Maven 就是一个帮你统一管理这些 jar 包、自动下载依赖、自动编译打包的工具。Maven 本身并不神秘它有两件核心武器依赖管理帮你把 jar 包从远程仓库拉下来存在本地和项目构建编译、测试、打包、部署这一整套流程。在 IDEA 里使用 Maven本质就是让 IDE 和这个构建工具协作把一条main方法跑通把项目变成一个规范化的工程。1.2 为什么 IDEA 2025.3.3 里必须会用 MavenIDEA 发展到今天几乎 Java 生态里的主流框架Spring Boot、MyBatis、Dubbo 等等都是基于 Maven 或 Gradle 构建的。你在 IDEA 2025.3.3 里创建一个普通 Java 项目当然也能跑但你一旦进入企业开发就会面对几十个依赖、多个模块、不同环境打包的问题。Maven 通过一个pom.xml文件把项目的依赖、构建顺序、插件配置全部固化下来——这也是团队协作时唯一能达成共识的东西。我见过不少朋友在 IDEA 里点了“New Project”之后完全不知道 “Build Tool” 那一栏该选什么。如果你选 Non-Build Tool后面写 Spring Boot 时会非常痛苦。用 Maven 不是说它完美而是它目前依然是 Java 项目里最通用、参考资料最多、团队协作成本最低的方案。1.3 本教程锁定的版本与环境组合我下面写的每一步都基于这套组合操作系统为 Windows 11macOS 操作逻辑基本一致差异处我会单独标注JDK 版本为常见的 1.8 或 17Maven 版本为 3.9.x稳定兼容性好IDEA 版本为标题中的 2025.3.3。这套组合的好处是JDK 8 是很多老项目还在用的底线JDK 17 又是现在新项目的主流IDEA 2025.3.3 内置了对两者都非常稳定的支持Maven 3.6 以上版本两个 JDK 都能正常驱动不会出现“IDEA 版本太新导致 Maven 插件失灵”的诡异问题。2. 环境准备Maven 下载、安装与配置很多新手卡在这一步就不动了。IDEA 虽然自带了 Maven但我在实际教学中强烈推荐你自己单独安装一份 Maven并配置好环境变量。原因是IDEA 内置的 Maven 版本有时会随着 IDE 更新而变化而你项目里的pom.xml可能对版本有要求自己装一份可以固定版本、随时切换、不受 IDE 升级影响。没有 IDEA 时也能用命令行操作项目这是团队协作和 CI/CD 的基础。2.1 第一步先确认 JDK 环境Maven 本身是 Java 写的运行它必须要先有 JDK。安装 JDK 之后打开命令行窗口Windows 用win R输入cmdmacOS 用终端输入java -version。如果你能看到版本信息说明 JDK 已经就绪如果提示“不是内部或外部命令”那就是 JAVA_HOME 环境变量没配好。提示JDK 只是用来“跑”Maven 和编译项目的IDEA 2025.3.3 自身也依赖 JDK 启动两者缺一不可。装好 JDK 后建议把JAVA_HOME环境变量也一并配置Windows 下在“系统属性 → 环境变量 → 新建”变量值填 JDK 安装目录比如C:\Program Files\Java\jdk-17然后编辑 Path加入%JAVA_HOME%\bin。2.2 从官网下载 Maven 压缩包直接去 Apache Maven 官网下载二进制压缩包注意是apache-maven-3.9.x-bin.zip别下成源码包下载后解压到一个路径中不含中文和空格的目录。我个人建议放D:\dev\apache-maven-3.9.9或 macOS 下的~/dev/apache-maven-3.9.9尽量避免放桌面或“下载”文件夹因为后面编译器扫描路径时特殊字符容易带来不可预判的问题。2.3 配置环境变量Windows 系统新建系统变量MAVEN_HOME值填 Maven 解压目录再编辑 Path新增%MAVEN_HOME%\bin。macOS 则在~/.zshrc里加export MAVEN_HOME/Users/你的用户名/dev/apache-maven-3.9.9和export PATH$PATH:$MAVEN_HOME/bin然后source ~/.zshrc。配置完毕后重新打开一个命令行窗口输入mvn -v。如果能看到类似Apache Maven 3.9.9和 JDK 版本信息说明环境已经通了一半。2.4 配置阿里云镜像仓库解决依赖下不动的问题这一步是很多新手最容易忽略的。默认的 Maven 中央仓库在国外国内网络下经常出现“下载到一半卡死”或“Could not transfer artifact”报错。阿里云有一个公共加速仓库速度稳定得多。在 Maven 安装目录下的conf/settings.xml中找到mirrors标签可能在注释里加入这段配置mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror这里mirrorOf写central意思是“只拦截中央仓库的下载请求”其他自定义仓库不受影响这是最稳妥的镜像写法。配置位置要注意settings.xml是 Maven 的全局配置文件IDEA 里项目层面的settings.xml优先级更高但新手阶段你只需要管好全局这份就够了。2.5 两个本地仓库怎么合并热搜里大家最关心的问题我搜索时看到很多人问“我有两个 Maven 本地仓库 repository怎么合并”。这事得说清楚本地仓库实际上不建议手动合并。为什么因为本地仓库里的目录结构是按groupId/artifactId/version组织的而且缺少_remote.repositories等元数据文件时你就算把文件复制过去Maven 也可能不认。我踩过这个坑强行合并之后依赖依然报错最后被迫删掉重下。正确做法是确定一个仓库作为默认仓库在settings.xml里配置localRepository指向它。另一个仓库里如果有些“私有 jar 包”是正式仓库没有的那就把它们手动安装到新仓库里用命令行mvn install:install-file -Dfileold-repo-xxx.jar -DgroupIdcom.example -DartifactIddemo -Dversion1.0 -Dpackagingjar安装之后新仓库会生成对应目录和元数据比物理复制可靠得多。3. IDEA 2025.3.3 里创建 Maven 项目的完整操作现在进入核心环节。我假设你已经打开 IDEA 2025.3.3并且能看到欢迎界面或已经打开了一个旧项目。如果旧项目还开着先关掉回到欢迎页如果你直接新建项目IDEA 的配置不会被上一个项目的设置干扰。3.1 新建项目的关键选项点击New Project进入创建向导。这里有几个字段需要仔细看Name你的项目名比如hello-maven项目名不要用中文不要带空格。Location项目保存位置同样建议放纯英文路径的目录下。Language选 Java。Build system这里要选Maven。这是 IDEA 2025.3.3 里很显眼的一栏如果你选了 IntelliJ 或者其他选项创建出来的项目结构就不是 Maven 风格后面会很别扭。JDK选你安装好的 JDK。如果下拉框为空点击 Add JDK 手动指定 JDK 安装目录。GroupId / ArtifactId这两个概念一开始不用理解太深简单记一下groupId一般是公司域名倒写比如com.exampleartifactId是项目名比如hello-maven。这是 Maven 项目在仓库里的“坐标”后面会一直用到。关键操作这里很多教程会漏掉一个细节——在创建向导的最底部通常没有专门用来指定 Maven 路径的选项。你在向导里点完 Create 之后见到的项目其实已经在用 IDEA 内置的 Maven。我不建议新手一上来就去改 IDEA 内置 Maven 设置原因很简单mvn -v验证过的外部 Maven 和 IDEA 内置 Maven 本质行为一致但外部版本可控可换。如果你想使用自己安装的 Maven需要在后续的 Settings 里指定路径这个我在 3.2 节讲。3.2 指定 IDEA 2025.3.3 使用你自己的 Maven项目创建完成后进入File → SettingsmacOS 是IntelliJ IDEA → Preferences在左侧搜索框输入Maven找到Build, Execution, Deployment → Build Tools → Maven。在这一页里你会看到Maven home path这是最重要的一项。点击右侧文件夹图标选择你解压的 Maven 目录比如D:\dev\apache-maven-3.9.9。如果你不设置IDEA 会默认使用内置 Maven但版本可能不如你预期。User settings file这里要指定settings.xml。如果你之前在 Maven 的conf/settings.xml里配了阿里云仓库可以把这里的路径指向那个文件。IDEA 会自动读取本地仓库路径和镜像配置。Local repository正常情况下它会自动读取settings.xml里的localRepository你不需要手动填如果你看到这里显示 IDEA 默认路径比如C:\Users\xxx\.m2\repository说明它没读到你的 settings.xml点Override手动填一下也可以。设置完成后点击Apply和OK。然后看 IDEA 右侧工具栏应该能看到Maven面板一个带 M 图标的侧边栏。如果没有去View → Tool Windows → Maven打开。3.3 创建后项目结构为什么没有 src 目录这是我在回答里出现频率最高的问题“明明项目创建成功了为什么src目录不在了”在 IDEA 2025.3.3 里如果你在创建向导中选择的是 Maven 模板但后续没有选择 Archetype即“不带骨架”那么创建出来的项目结构默认是“空壳”的——只有一个pom.xml没有src/main/java、src/main/resources这样的目录。这是正常现象不是安装坏了。要解决有两种方式。第一种是在src目录处右键New → Directory手动创建main/java、main/resources、test/java、test/resources这四个目录取决于你的需要。第二种更推荐直接在 pom.xml 里配置好插件后让 IDEA 自动识别结构。我建议按第二种来走最终目录结构如下hello-maven ├── pom.xml └── src ├── main │ ├── java │ │ └── com │ │ └── example │ │ └── Main.java │ └── resources └── test └── java创建完目录后右键src/main/java目录选择Mark Directory as → Sources Root这一步很关键否则 IDEA 不认为它是源码目录Main.java中的main方法不会出现运行箭头图标。src/test/java同理标记为Test Sources Root。3.4 把 Maven 面板用起来创建好目录结构后我建议你先看一眼 IDEA 右侧的 Maven 面板。这个面板列出了Lifecycle生命周期、Plugins插件、Dependencies依赖等折叠项。你在 IDEA 里点击运行项目时其实底层就是帮你执行 Maven 的某个生命周期阶段。后面如果遇到“IDEA 里运行正常但命令行报错”的情况很大概率就是这里的 Maven 配置和命令行不一致。注意IDEA 2025.3.3 默认会开启 Maven 的“自动导入”功能当pom.xml改变时会自动下载依赖。如果偶尔出现新加入的依赖没有生效点 Maven 面板顶部的刷新按钮两个旋转箭头图标即可这个操作叫Reload All Maven Projects。4. pom.xml 配置详解让项目真正可运行pom.xml是整个 Maven 项目的核心。很多新手以为它是自动生成的、不需要管其实恰恰相反项目能不能跑通一半看这个文件。4.1 最小可运行的 pom.xml 长什么样IDEA 自动生成的pom.xml大概长这样?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdhello-maven/artifactId version1.0-SNAPSHOT/version properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /project这里面最容易被忽略的就是properties标签里的三个配置。maven.compiler.source和maven.compiler.target决定了编译时用的 Java 语法级别如果这里写的是 17而你本机 JDK 是 8那么编译会报“不支持发行版本 17”之类的错误。你要么把这两个改成 8要么把 JDK 升级到 17二选一不要乱试。4.2 如何添加依赖并以 JUnit 为例新项目的pom.xml是空壳没有依赖。那么依赖从哪里来答案是从 Maven 仓库来。你在dependencies标签里写上依赖坐标Maven 会去本地仓库找找不到就去远程仓库比如阿里云镜像下载。以最常见的单元测试依赖 JUnit 5 为例dependencies dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version5.10.2/version scopetest/scope /dependency /dependencies添加这段配置后点击 Maven 面板刷新等待右下角下载进度条走完Dependencies下面就会多出junit-jupiter一栏。如果半天没反应参考第 2.4 节检查阿里云镜像配置是否生效。scope 的含义我顺便说一下test表示这个依赖只在测试阶段生效打包不会带进正式产物compile是默认值编译和运行都需要provided表示编译时需要但运行时由环境提供。新手阶段懂这三个就够用了。4.3 配置编译插件解决“程序包不存在”和版本骚乱如果你在项目里引入第三方依赖编译时偶尔会遇到“程序包不存在”但代码里 import 明明是对的。这个问题的常见原因有两个一是依赖坐标写错二是 maven-compiler-plugin 的版本和你用的 JDK 不兼容。为了稳定我习惯在pom.xml的build标签里显式指定编译插件版本build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.13.0/version configuration source17/source target17/target encodingUTF-8/encoding /configuration /plugin /plugins /build这里的source和target与properties里的设置是呼应的。显式写出插件版本之后依赖就不会受 IDEA 内置默认插件版本的影响团队其他人拉下代码也能得到一致结果。4.4 配置可执行 jar 包插件如果你希望项目能“打包成一个可双击运行的 jar”那么上面这些还不够。默认的 jar 插件打出的包没有主类清单信息运行java -jar会报“没有主清单属性”。解决方式是在build/plugins里再加一个 maven-shade-plugin 或 maven-jar-plugin。新手我更推荐 maven-shade-plugin因为它的可执行包是“fat jar”——把所有依赖打在一起不用管 classpath 问题plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-shade-plugin/artifactId version3.5.3/version executions execution phasepackage/phase goals goalshade/goal /goals configuration transformers transformer implementationorg.apache.maven.plugins.shade.resource.ManifestResourceTransformer mainClasscom.example.Main/mainClass /transformer /transformers /configuration /execution /executions /plugin配置好后在 Maven 面板Lifecycle里双击package就会在target目录生成一个hello-maven-1.0-SNAPSHOT.jar和一个original-xxx.jar后者是原始小 jar前者才是可以直接运行的。5. 让项目跑起来三种运行方式配置说再多最终目的是让main方法跑起来。下面我说三种运行方式从最简单到稍复杂按需选择。5.1 方式一IDEA 里右键直接运行在src/main/java/com/example/Main.java里写一个 main 方法然后点类名左侧出现的绿色三角形箭头。IDEA 会直接编译并运行这个类所有 Maven 依赖都会被自动加入 classpath。这是新手最常用也最顺的方式。但这种方式有一个坑它绕过了一部分的 Maven 命令生命周期。如果你在pom.xml里配置了资源过滤或模块化功能右键运行可能不会完全触发这些配置行为会跟命令行mvn不一致。所以我会建议你至少知道后面两种方式。5.2 方式二命令行执行 mvn compile / mvn clean install在 IDEA 自带的终端面板或外部命令行里进入项目根目录执行mvn compile这个命令只编译主代码不会跑测试不会打包。执行后会在target/classes目录下生成.class文件。接下来可以执行mvn clean install这个命令的执行顺序是清理target目录 → 编译主代码 → 执行测试 → 打包 → 安装到本地仓库。install操作是很多新人不理解的它会把你的项目产物安装到本地 Maven 仓库让本机其他 Maven 项目可以通过坐标引用到这个包相当于“上架到本地货架”。常见热搜词里的clean install就是这个命令。正确执行一次完整的 clean install心里基本就有底了依赖正常、测试通过、打包无误项目是健康的。5.3 方式三打包可执行 jar 后运行在配置了 4.4 节的 shade 插件之后执行mvn clean package java -jar target/hello-maven-1.0-SNAPSHOT.jar如果控制台顺利输出Hello Maven或者你的业务日志说明项目已经真正“可运行”了。这一步的意义在于它模拟了部署到服务器后的运行方式依赖不再由 IDEA 管理而是打进 jar 里自行运转。这里我想提醒一下新手刚开始用java -jar很容易遇到跟我们本地运行结果不同的情况原因大多是依赖没有被打进包或者主类信息设置错误。此时不要慌回到 4.4 节检查 shade 插件的mainClass是不是写全限定名包括包名。6. 新手必踩的坑与排错指南这些坑我见的实在太多了挑几个最有代表性的集中说一下排查思路和坑为什么会出现都讲透。6.1 依赖下载报错“Could not transfer artifact”这个报错的核心是网络问题。解决办法优先级从高到低首先确认阿里云镜像有没有配置对其次检查本地仓库路径是否被占用最后看是否因为公司防火墙限制。如果你配了阿里云镜像还是报错有一个检查方法在 Maven 面板里查看依赖的下载 log。打开 IDEA 右下角会有一个后台任务进度条点开它能看到具体卡在哪个 url 上。如果你看到的是repo.maven.apache.org说明设置没生效这时检查settings.xml的镜像mirrorOf是否写成了*而不是central。提示mirrorOf写成*并不是不行但它会把包括你自己配置的私有仓库在内的所有请求都拦截到阿里云有时会适得其反。我建议用central就够了先用最简单的配置把依赖问题解决再考虑多仓库的复杂度。6.2 本地仓库出现.lastUpdated文件依赖永远提示失败这是另一个高频问题。当你某次依赖下载中断Maven 会在本地仓库对应目录生成.lastUpdated结尾的文件记录“上次更新失败”的状态。这个文件很烦人——它存在时 Maven 不会重新下载依赖必须把对应目录删掉。我提供的排查步骤是找到报错依赖的坐标去本地仓库对应目录下看有没有.lastUpdated文件有就删掉整个version目录然后点 Maven 面板刷新重新下载。这种方式比在 IDEA 里执行“Invalidate Caches”更精准速度也快。6.3 IDEA 里没有 Maven 侧边栏也没有刷新按钮如果你创建项目时没有选 Maven 作为 Build systemIDEA 默认不会出现 Maven 面板。解决方式是在项目根目录的pom.xml上右键选择Add as Maven Project。IDEA 识别到 pom.xml 后会自动导入 Maven 项目并显示侧边栏。这个操作属于“事后补救”适用于已经创建了普通 Java 工程但后来想转成 Maven 的情况。6.4 clean install 时报“程序包不存在”或“找不到符号”这种报错往往不是因为代码真的有问题而是因为项目之间的模块依赖没有安装到本地仓库。举一个最常见的场景你有两个模块 A 和 BB 依赖 A。如果你只对 B 执行mvn clean installMaven 会去本地仓库找 A 的 jar如果 A 还没有 install 过就会报“程序包不存在”。解决办法是按依赖顺序先 install 底层模块先进入 A 模块执行mvn clean install -DskipTests再进入 B 模块执行构建。-DskipTests是跳过测试因为 install 时如果测试代码有问题会被卡住跳过测试能让安装先完成后面再单独定位测试问题。6.5 Spring Boot 项目跑不起来application.yml 没有被扫描到如果你创建的项目依赖了 Spring Boot你又手动建立了src/main/resources目录但运行时报“找不到配置文件”。这是 IDEA 对资源目录识别的问题手动建的resources目录没有标记为 Resources Root。右键resources目录选择Mark Directory as → Resources Root即可解决。这个操作很多新手不知道但它和前面Sources Root一样是 IDEA 识别目录类型的关键手段做完这一步application.yml或logback.xml才能被正确打包进 classpath。其实你已经是“勉强能用 Maven”的状态了这整篇教程走下来你已经经历了从环境准备到实际运行完整的 Maven 项目生命周期应该能感觉到Maven 并没有想象中那么可怕。我的个人经验是第一次用 Maven 的时候不求理解所有原理只求能规范地创建项目、添加依赖、跑通 build。真正做到这一点之后遇到的报错基本都能在网上找到对应答案因为你已经知道报错在哪个环节了。最后再分享一条我自己的习惯每个项目创建完成后我都会先在命令行里执行一次mvn clean install确认这个项目脱离 IDEA 也能独立构建。这样做的原因很简单——IDEA 的自动化和图形化会给新手一种“一切都很顺利”的错觉只有命令行才能真实反映环境是否干净、配置是否正确。你把这个习惯保持下来后面无论是换电脑、接新项目还是参与团队协作都会比别人走得稳。