拓冰网站定制 
前两天有群友在群里问“怎么创建 mevan 项目”我盯着这个拼写看了好几遍第一反应是好家伙Maven 被你拼成这样。但仔细一想这个拼写失误恰恰暴露了很多新手在这个环节的真实状态——听说过 Maven知道 IDEA 新建项目列表里有它却完全不清楚 Maven 到底是干嘛的也不知道创建完之后那一堆 src 目录和 pom.xml 到底有什么意义。这篇文章就是冲着这件事来的。我准备把“创建 Maven 项目”这条线从头到尾拆开讲Maven 解决什么问题、怎么安装、怎么在 IDEA 里创建第一个项目、pom.xml 的依赖管理逻辑、阿里云镜像仓库配置以及那些几乎人人都会撞上的坑——依赖下载失败、.m2 目录里没有 settings.xml、Maven 工具栏突然消失。我尽量用实际项目里的口吻来讲你照着操作就能跑通。1. Maven 到底是干嘛的从一次 jar 包依赖地狱说起1.1 没有 Maven 之前Java 项目是怎么被 jar 包逼疯的我入行前几年Java 项目还流行“lib 目录塞 jar 包”的年代。当时的典型操作是去官网或者第三方站点手动下载 jar然后放进WEB-INF/lib再在 IDE 里把这一堆 jar 逐个加入构建路径。听起来很简单实际上三天两头出问题。最常见的场景是同一个项目在不同人电脑上行为不一致。张三电脑上commons-lang3-3.7.jar放在 lib 里李四电脑上可能放着commons-lang3-3.5.jar代码里调用的某些方法在 3.5 里根本不存在一运行就NoSuchMethodError。这还算好的。更恶心的是两个框架对同一个依赖有不同版本要求比如老的业务模块需要commons-collections 3.x新引入的框架又需要4.x。有人图省事把两个版本同时丢进 lib结果启动时类加载器直接抓到 3.x 的类4.x 的新 API 全部ClassNotFoundException。那时候排查这个问题的方式很原始一个类一个类地搜 jar 包用压缩软件打开 jar 看字节码版本再去网上重新下载。一个下午基本就搭进去了。后来有了 Maven我最大的感受不是“下载依赖变简单了”而是“项目的可复现性终于变高了”——同一份代码不管谁 checkout 下来执行同一个命令拉下来的依赖版本是一致的。1.2 Maven 的三板斧目录约定、坐标定位、生命周期Maven 解决依赖问题靠的不是什么黑魔法而是三个核心设计。第一个是固定目录结构。Maven 规定你的源码必须放在src/main/java资源放src/main/resources测试代码放src/test/java。这套约定俗称“约定大于配置”你不需要写一堆 XML 去告诉构建工具源码在哪里只要目录放对它自己就知道怎么编译。第二个是依赖坐标。每个依赖在 Maven 里都有一个唯一的定位方式groupId artifactId version。这三个值组合起来相当于一个 jar 包的“收货地址”。Maven 先在本地仓库里找找不到就去远程仓库下载并缓存到本地下次再用就不需要重复下载了。第三个是构建生命周期。Maven 把构建过程拆成clean、compile、test、package、install、deploy这些阶段。执行mvn clean install的时候它会按照顺序完成编译、测试、打包和安装到本地仓库。你不用自己去记“编译完再复制到哪、测试怎么跑、jar 包放哪”Maven 全给包办了。这里我要特别强调一个概念依赖传递。你往 pom.xml 里加一个spring-boot-starter-webMaven 会自动把 Spring MVC、Tomcat、Jackson 这些间接依赖统统拉下来。这就是为什么很多新手看到“只加了一个依赖却下载了几十个 jar 包”时一脸懵。不要慌这是正常现象Maven 正在自动处理依赖树。2. 环境准备与安装JDK、Maven、环境变量配置一次理清2.1 Maven 版本怎么选别一上来就追最新版先回答一个很实际的问题下载哪个版本Maven 官网会同时提供多个版本当前主流的稳定版本大概在 3.8.x 到 3.9.x网上也能看到 3.6.3 的下载地址。我的建议是选 3.8.x 或 3.9.x 的稳定版不太建议新项目直接用 Maven 4.x——倒不是说它不能用而是很多 IDE 插件、旧项目的构建插件对 4.x 的兼容性还没有完全跟上没必要给自己挖坑。版本和 JDK 的对应关系简单整理了个表JDK 版本推荐的 Maven 版本备注JDK 8Maven 3.6.x / 3.8.x经典组合企业中大量存留JDK 11Maven 3.6.x / 3.8.x老项目升级常用JDK 17Maven 3.8.x / 3.9.x17 是当前很多新项目的选择JDK 21Maven 3.9.x较新 LTS建议 Maven 跟随新版本注意一个细节下载页面会有apache-maven-3.9.x-bin.tar.gz和apache-maven-3.9.x-src.tar.gz两种包。选 bin 那个src 是源码包普通使用不需要。2.2 Windows 和 Mac 的安装步骤环境变量到底该怎么配Windows 上安装 Maven 很简单核心三步把下载的压缩包解压到一个固定目录比如D:\apache-maven-3.9.6。路径里不要有中文和空格这是老生常谈但值得强调。新建系统环境变量MAVEN_HOME值指向解压目录。在Path变量里新增一行%MAVEN_HOME%\bin。打开新终端输入mvn -v看到输出里的Apache Maven和 Java 版本信息就说明安装成功了。Mac 上更省事用 Homebrew 一条命令就能搞定brew install maven如果你习惯手动安装也可以解压到/usr/local或家目录然后在~/.bash_profile或~/.zshrc里加export M2_HOME/Users/yourname/apache-maven-3.9.6 export PATH$M2_HOME/bin:$PATH改完记得执行source ~/.zshrc或source ~/.bash_profile让其生效。这一步很多新手会忘输入mvn -v提示找不到命令多半就是没 source。2.3 第一次运行本地仓库和 settings.xml 的正确认知装好 Maven 后我建议你立刻跑一条命令mvn help:system这条命令会触发 Maven 下载一堆基础插件下载到哪里呢默认是用户目录下的.m2/repository这个目录就是本地仓库。你可以把本地仓库想象成一个缓存区所有依赖先在这里查找找不到才去远程下载。你可能会问.m2目录里没看到 settings.xml 文件是不是装错了不是这非常正常。用户级的settings.xml是一个可选配置文件Maven 自带一套默认配置内部叫超级 POM没有用户级 settings.xml 时它照样能跑。只有你想修改默认行为——比如指定本地仓库位置、配置阿里云镜像、连接私有仓库时——才需要手动创建这个文件。如果你想知道当前 Maven 到底用了哪些生效配置可以直接用mvn help:effective-settings它会打印出合并后的最终配置包括本地仓库路径、镜像列表、代理信息。排查“为什么我改了 settings.xml 却不生效”这个问题时这条命令是神器。3. 用 IDEA 创建 Maven 项目从 New Project 到 Hello World一步步看3.1 新建 Project那些让人懵圈的字段分别是什么意思我以 IDEA 2024/2025 版的操作为例步骤基本一致。打开 IDEA选择New Project左侧选择Maven有些新版界面上叫Build Tool: Maven。然后你会看到几个需要填写的字段。Name项目名称一般也是模块名。Location项目存放路径。GroupId组织标识。通常填公司或组织的域名反写比如com.example。它决定了你项目坐标的第一个层级。ArtifactId项目标识。一般填项目名比如demo-project。它对应最终生成的 jar 包名前缀。Version版本号。开发阶段通常填1.0-SNAPSHOTSNAPSHOT 表示快照版。很多教程里会建议勾选某个archetype骨架模板比如maven-archetype-quickstart。我的建议是新手阶段不要勾任何 archetype直接创建一个最干净的空项目。因为 archetype 模板会生成一些你可能用不到的文件干扰理解。空项目自动生成的 pom.xml 非常干净适合一点点往里加内容。3.2 标准目录结构和第一个 Java 类项目创建完成后你会看到 IDEA 自动生成这样的目录结构demo-project/ ├── pom.xml └── src/ ├── main/ │ ├── java/ │ └── resources/ └── test/ ├── java/ └── resources/这个结构请务必记牢。src/main/java放正式代码src/main/resources放配置文件src/test/java放单元测试。Maven 编译、打包时都按照这套规则来找文件目录放错代码写得再好也进不了最终产物。接下来在src/main/java下新建一个包比如com.example再创建一个测试类package com.example; public class Hello { public static void main(String[] args) { System.out.println(Hello Maven); } }直接右键运行这个 main 方法看到输出后说明你的 JDK 和编译环境已经通了。但注意这里跑的是 IDEA 自己的编译还没经过 Maven。想确认 Maven 编译正常可以打开 IDEA 右侧的 Maven 工具窗口在Lifecycle列表里双击compile。完成后去target/classes目录看一眼你会发现编译出来的.class文件老老实实躺在那里。3.3 IDEA 里的 Maven 配置别让默认值坑了你IDE 有自带的 Maven但生产环境建议指到你命令行里安装的那套这样两边行为完全一致。打开Settings - Build, Execution, Deployment - Build Tools - Maven注意三个字段Maven home path填你安装的 Maven 路径比如D:\apache-maven-3.9.6。User settings file指定 settings.xml 路径。可以选 Maven 安装目录conf/settings.xml也可以选用户级~/.m2/settings.xml。填了之后 IDEA 会读取这个文件里的镜像、本地仓库配置。Local repository本地仓库路径。如果你在 settings.xml 里配了localRepository这里通常会自动读取并同步显示。这三项一定要保持一致否则会出现“命令行能下载依赖IDEA 里却报红”的诡异情况。IDEA 右侧那个 Maven 工具窗口需要认识一下。它分为几个模块Lifecycle生命周期命令、Plugins插件、Dependencies依赖列表。在Lifecycle里双击packageMaven 就会编译、跑测试并产出 jar 包产物在target/目录下。这里补充一个非常容易踩的坑如果你的项目是 Spring Boot 项目直接用mvn package打出的 jar可能无法用java -jar直接运行因为普通 package 打出的 jar 不会把项目依赖打包进去。必须额外配置 Spring Boot 的打包插件spring-boot-maven-plugin它会生成一个可执行 fat jar。这个后面讲 pom 配置时会说到。4. pom.xml 的依赖管理逻辑坐标、scope、parent 这些必须弄明白4.1 坐标与依赖传递为什么只加一个依赖却下载了几十个 jarpom.xml 是 Maven 项目的核心文件所有依赖都在这里声明。举个例子dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependencygroupId是组织坐标artifactId是模块坐标version是版本坐标。三项合起来Maven 就能在仓库中唯一定位到一个 jar。本地仓库里的目录结构其实也是按坐标路径放的比如org/springframework/boot/spring-boot-starter-web/所以坐标写错哪怕一个字母下载路径就完全对不上。依赖传递是 Maven 里最容易产生困惑的机制。你引入spring-boot-starter-web它会自动携带spring-webmvc、jackson-databind等间接依赖。这些间接依赖有自己的版本号当多个依赖都牵涉到同一个库且版本不一致时就会产生依赖冲突。排查依赖冲突的标准姿势是用mvn dependency:treemvn dependency:tree输出里会以树形结构展示整个依赖图谱谁的依赖是谁引出来的一目了然。Maven 处理冲突有一个默认规则路径越短越优先路径相同先声明的优先。这个规则偶尔会把正确的版本覆盖掉到这种时候通常就要显式声明需要的版本号来“纠正”冲突。4.2 parent 与统一版本管理别再一个版本号写十遍当一个项目里有多个模块或者你希望所有子项目统一使用某个框架版本最好的做法是引入 parent 机制。Spring Boot 项目最典型parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent继承这个 parent 之后你的 pom 里引入各种spring-boot-starter-*依赖时可以不写版本号由 parent 统一管理。这个机制的核心是dependencyManagement——父 POM 里声明了依赖版本子模块只负责引用不负责写版本。如果你的项目不想继承 Spring Boot 的 parent也可以自己在dependencyManagement里管理版本properties spring.boot.version2.7.18/spring.boot.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring.boot.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement多模块项目里父模块的packaging会设成pom表示它只是一个聚合模块不产出 jar。子模块之间如果需要互相依赖直接按坐标引用即可。4.3 scope 的作用搞清楚依赖到底要不要打进 jarpom.xml 里每个依赖都可以配置scope新手经常忽略它结果打包后 jar 体积失控或者运行时报错。几种 scope 的适用场景scope什么时候用是否打进最终产物compile默认值业务代码直接使用的依赖比如 Spring MVC会provided编译时需要但运行环境已经自带比如 servlet-api、lombok不会runtime编译期用不到运行期才需要比如 MySQL 驱动会test只在测试代码里用比如 JUnit不会最经典的是 servlet-api你的代码编译时要用到HttpServletRequest但部署到 Tomcat 后 Tomcat 自带这个 jar如果打进去反而会和容器冲突。所以要用provided。JDBC 驱动就是另一个例子。代码里用的是java.sql.DriverManager接口本身是 JDK 的只有运行时才需要连接到 MySQL 驱动实现所以可以用runtime来声明。4.4 一段可以直接抄的完整 pomb 示例我给一个新手最常遇到的“Spring Boot Web 项目”最小配置?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 parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIddemo-project/artifactId version1.0-SNAPSHOT/version namedemo-project/name properties java.version8/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这个配置里spring-boot-maven-plugin就是前面说的“打可执行 jar 的关键”。没有它mvn package只会打一个普通 jar里面只有项目自己的类没有依赖有了它才会把依赖和启动器一起打包java -jar才能直接启动。5. 镜像仓库配置与依赖加速阿里云、多镜像、deploy 发布这些都要说5.1 Maven 默认仓库太慢在 settings.xml 里配阿里云镜像Maven 默认从中央仓库repo.maven.apache.org下载依赖这个仓库服务器在海外国内访问速度经常不理想尤其是下午到晚间高峰期。解决办法是配置镜像仓库把“所有依赖都先去镜像站拉”的规则写在 settings.xml 里。在用户级~/.m2/settings.xml中配置没有这个文件就新建一个核心片段如下settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepositoryD:/maven-repository/localRepository mirrors mirror idaliyunmaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*/mirrorOf /mirror /mirrors /settings这段配置做了两件事第一把本地仓库改到了D:/maven-repository避免 C 盘越积越大第二配置一个mirrorOf为*的阿里云镜像意思是“所有仓库的请求都走阿里云”。这里要特别提醒maven.aliyun.com/repository/public是一个聚合仓库里面同时代理了中央仓库、spring 仓库、jboss 仓库等常用仓库。对绝大多数项目来说这一个镜像就够了。配置完记得在 IDEA 的 Maven 设置里把User settings file指到这个文件然后执行Reload All Maven Projects让配置重新加载。如果改了没反应先跑一下mvn help:effective-settings看看镜像到底有没有生效。5.2 多个镜像怎么配mirrorOf 的坑千万别踩有些人配了多个镜像比如阿里云一个、华为云一个、腾讯云一个心想“这个挂了还能用那个”。但 Maven 的 mirror 匹配机制和直觉不太一样它按声明顺序找到第一个匹配的 mirror 就直接使用不会因为下载失败就自动切换到下一个。所以多个 mirror 的mirrorOf不要都写成*那样基本只有一个生效。正确的做法是区分用途一个专属镜像用来加速中央仓库mirrorOf设为central。某些特殊依赖走专用仓库通过repositories节点指定而不是靠 mirror 拦截。需要动态切换镜像时用 profile 打包不同 settings而不是在一个 settings 里堆一堆 mirror。示例只想加速中央仓库同时保留其他仓库原样访问mirror idaliyun-central/id namealiyun central/name urlhttps://maven.aliyun.com/repository/central/url mirrorOfcentral/mirrorOf /mirror如果你在公司内网使用还要注意公司可能自建了私有仓库Nexus 或 Artifactory这时候正确姿势是把私服地址配成中央仓库的镜像或者通过repositories指向私服让 Maven 优先从私服拉取。私服里有就缓存给团队成员没有再去远程拉这样既能加速又能做统一管控。5.3 怎么把项目发布到远程仓库mvn deploy 的完整设置当你需要把打好的 jar 分享给其他团队使用时最简单的方式是执行mvn deploy把构件部署到远程仓库。这个远程仓库可以是公司私服也可以是云厂商的制品仓库。先在 pom.xml 里配置发布地址distributionManagement repository idreleases/id nameRelease Repository/name urlhttp://nexus.example.com/repository/maven-releases//url /repository snapshotRepository idsnapshots/id nameSnapshot Repository/name urlhttp://nexus.example.com/repository/maven-snapshots//url /snapshotRepository /distributionManagement注意id要和 settings.xml 中的server的id对应。如果私服需要账号认证在用户级 settings.xml 中加入servers server idreleases/id usernamedeploy-user/username passworddeploy-password/password /server server idsnapshots/id usernamedeploy-user/username passworddeploy-password/password /server /servers然后执行mvn deployMaven 会根据当前项目的 version 后缀自动判断发布到哪个仓库1.0-SNAPSHOT会进快照仓库1.0.RELEASE会进正式发布仓库。快照版本最显著特点是“可以重复发布同一个版本”别人再次构建时可能会拉到更新的内容正式版本则是发布后不再变化的稳定版本。6. 高频踩坑依赖报错、settings.xml 缺失、Maven 工具栏消失一次讲透6.1 依赖突然标红、报 “Download from maven failed” 的完整排查链路这个坑我相信 80% 的 Maven 用户都踩过pom.xml 里某个依赖标红或者 IDEA 底部弹出Download from maven failed。我见到最离谱的一次是有人把spring-boot.version写成了2.13.0——这个版本根本不存在坐标错得离谱IDE 当然找不到。遇到依赖报错不要急着删.m2目录按下面顺序排查。第一步确认坐标。打开 Maven 中央仓库网站或阿里云仓库网页版搜一下你写的groupId : artifactId : version组合到底存不存在。版本号写错、字母大小写写错是最常见原因。第二步看 Maven 是否处于离线模式。IDEA 的 Maven 设置里有一个Offline work开关新手有时误点开之后所有依赖都不再联网下载只能搜本地仓库。本地仓库里没有就直接报 red。检查这个开关是否关闭。第三步看本地仓库里有没有*.lastUpdated文件。Maven 下载依赖失败时会在本地仓库留下这种临时标记文件。下次想重新下载必须先把这些失败标记清理掉。可以精确删除对应依赖目录# 比如删除 spring-boot 相关失败缓存 rm -rf ~/.m2/repository/org/springframework/boot然后再执行mvn clean install --update-snapshots或者直接在 IDEA 里点击Reload All Maven Projects强制重新解析。第四步看 IDEA 使用的 settings.xml 和你命令行里的是不是同一个。很多人设置里指了 A 文件命令行默认用的是 B 文件两边配置不一致就会出现“命令行能下成功IDEA 里一直报失败”。这套排查链路走下来90% 的依赖报错都能解决。6.2 .m2 目录里没有 settings.xml 到底要不要新建“我的.m2目录下没有 settings.xml 文件是不是环境坏了”——这个问题我在各大技术社区见过无数次。答案是没有 settings.xml 完全正常它不是 Maven 的必需文件。Maven 在没有用户级 settings.xml 时会使用安装目录conf/settings.xml作为全局配置如果全局配置也没有改过那就走默认中央仓库。所以你不建任何 settings.xmlMaven 一样可以工作。只有出现以下需求时才需要新建想指定本地仓库位置想配置阿里云镜像或私有仓库需要为特定仓库配置账号认证想统一设置 JDK 编译版本。新建用户级 settings.xml 时放在~/.m2/settings.xml即可。最简模板settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepository${user.home}/.m2/repository/localRepository mirrors mirror idaliyunmaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*/mirrorOf /mirror /mirrors /settings改完之后同样去检查mvn help:effective-settings确认mirrors节点里确实有你的配置。如果仍然走默认仓库大概率是你把文件名搞错了比如写成了settings.xml.txtWindows 默认隐藏扩展名时很容易犯这个错。6.3 IDEA Maven 工具栏不见了、项目识别不了怎么治有一个很日常却很烦人的状况打开项目后发现右侧没有 Maven 工具窗口或者 IDEA 提示“不是 Maven 项目”。处理顺序我建议按“轻”到“重”来。第一个办法看窗口是不是被折叠了。IDEA 的新版界面所有侧边栏都可以手动收起右侧如果只有一个小竖条点一下展开Maven面板就行。路径是View - Tool Windows - Maven。第二个办法手动把项目关联为 Maven 项目。在项目里找到pom.xml右键选择Add as Maven ProjectIDEA 会重新识别这个项目结构。第三个办法关闭项目后删除.idea目录再重新打开项目。.idea目录是 IDEA 的项目配置缓存里面如果存了错误的项目识别信息会导致项目一直不被当 Maven 看待。删除后重新导入IDEA 会从零解析 pom.xml。看到 Maven 面板了但Lifecycle下面没有命令也可以执行右侧工具栏里的刷新按钮Reload All Maven Projects触发一次重新加载。还有一种情况是 IDEA 版本升级后老项目里的.idea配置和新版本冲突删掉重来往往就好了。6.4 几个“小毛病”的补救JavaFX 项目、旧系统、中文路径最后补充几个小场景。JavaFX 项目加 Maven 配置核心依赖是javafx-controls和javafx-fxml并且注意要给 Maven 编译插件指定 JDK 模块参数。如果 JDK 17 以上还需要配置maven-compiler-plugin并加入--add-exports之类的参数否则编译时会发生模块访问报错。老系统比如 Windows 7装 Maven先确认系统能装哪个版本的 JDK。Windows 7 自带或能装的一般是 JDK 8对应 Maven 3.6.x 最稳。太新的 Maven 版本可能因为 TLS 加密协议问题连不上中央仓库——这不是 Maven 有毛病而是老系统底层网络组件太旧换 3.6.x 通常能避开这个坑。安装路径含中文和空格会导致 Maven 在解析某些插件路径时出现诡异错误。一开始就把路径定在纯英文、无空白的目录下能省掉很多莫名其妙的麻烦。这个建议听起来很老土但在实际项目中踩中的人真的很多。说到打包如果你只是想快速生成一个可执行 jar 交差自己看一眼项目里有没有spring-boot-maven-plugin没有的话打出来的 jar 跑不起来别奇怪。普通库项目的 jar 是给别的项目依赖用的Spring Boot 项目的可执行 jar 是给java -jar用的这两种诉求对应的构建插件完全不同搞清楚自己想要哪一种再决定配不配插件。做 Maven 配置这件事我个人这几年最大的体会是能用最小配置跑通的东西就不要上来堆一大套。很多新人喜欢在网上找一份“全家桶”settings.xml 直接复制粘贴结果镜像配了四五个、仓库写了一大堆、还带了各种奇怪的 plugin 配置出了问题连是哪一层导致的都分不清。我自己的习惯是分步走先保证一条mvn -v能正常跑再保证mvn clean install能通最后才逐步加镜像、加仓库、加认证。每一步都通过命令行确认结果再回 IDEA 里做同样验证。Maven 不是那种“配置越复杂越专业”的工具它的价值恰恰在确定性——目录结构对了、坐标写对了、仓库配置对了剩下的事它替你搞定。把这个确定性建立起来后面再复杂的多模块工程、持续集成、制品发布都是在同一套逻辑上做加法而已。 Maven项目创建全攻略：从安装配置到依赖管理实战
前两天有群友在群里问“怎么创建 mevan 项目”我盯着这个拼写看了好几遍第一反应是好家伙Maven 被你拼成这样。但仔细一想这个拼写失误恰恰暴露了很多新手在这个环节的真实状态——听说过 Maven知道 IDEA 新建项目列表里有它却完全不清楚 Maven 到底是干嘛的也不知道创建完之后那一堆 src 目录和 pom.xml 到底有什么意义。这篇文章就是冲着这件事来的。我准备把“创建 Maven 项目”这条线从头到尾拆开讲Maven 解决什么问题、怎么安装、怎么在 IDEA 里创建第一个项目、pom.xml 的依赖管理逻辑、阿里云镜像仓库配置以及那些几乎人人都会撞上的坑——依赖下载失败、.m2 目录里没有 settings.xml、Maven 工具栏突然消失。我尽量用实际项目里的口吻来讲你照着操作就能跑通。1. Maven 到底是干嘛的从一次 jar 包依赖地狱说起1.1 没有 Maven 之前Java 项目是怎么被 jar 包逼疯的我入行前几年Java 项目还流行“lib 目录塞 jar 包”的年代。当时的典型操作是去官网或者第三方站点手动下载 jar然后放进WEB-INF/lib再在 IDE 里把这一堆 jar 逐个加入构建路径。听起来很简单实际上三天两头出问题。最常见的场景是同一个项目在不同人电脑上行为不一致。张三电脑上commons-lang3-3.7.jar放在 lib 里李四电脑上可能放着commons-lang3-3.5.jar代码里调用的某些方法在 3.5 里根本不存在一运行就NoSuchMethodError。这还算好的。更恶心的是两个框架对同一个依赖有不同版本要求比如老的业务模块需要commons-collections 3.x新引入的框架又需要4.x。有人图省事把两个版本同时丢进 lib结果启动时类加载器直接抓到 3.x 的类4.x 的新 API 全部ClassNotFoundException。那时候排查这个问题的方式很原始一个类一个类地搜 jar 包用压缩软件打开 jar 看字节码版本再去网上重新下载。一个下午基本就搭进去了。后来有了 Maven我最大的感受不是“下载依赖变简单了”而是“项目的可复现性终于变高了”——同一份代码不管谁 checkout 下来执行同一个命令拉下来的依赖版本是一致的。1.2 Maven 的三板斧目录约定、坐标定位、生命周期Maven 解决依赖问题靠的不是什么黑魔法而是三个核心设计。第一个是固定目录结构。Maven 规定你的源码必须放在src/main/java资源放src/main/resources测试代码放src/test/java。这套约定俗称“约定大于配置”你不需要写一堆 XML 去告诉构建工具源码在哪里只要目录放对它自己就知道怎么编译。第二个是依赖坐标。每个依赖在 Maven 里都有一个唯一的定位方式groupId artifactId version。这三个值组合起来相当于一个 jar 包的“收货地址”。Maven 先在本地仓库里找找不到就去远程仓库下载并缓存到本地下次再用就不需要重复下载了。第三个是构建生命周期。Maven 把构建过程拆成clean、compile、test、package、install、deploy这些阶段。执行mvn clean install的时候它会按照顺序完成编译、测试、打包和安装到本地仓库。你不用自己去记“编译完再复制到哪、测试怎么跑、jar 包放哪”Maven 全给包办了。这里我要特别强调一个概念依赖传递。你往 pom.xml 里加一个spring-boot-starter-webMaven 会自动把 Spring MVC、Tomcat、Jackson 这些间接依赖统统拉下来。这就是为什么很多新手看到“只加了一个依赖却下载了几十个 jar 包”时一脸懵。不要慌这是正常现象Maven 正在自动处理依赖树。2. 环境准备与安装JDK、Maven、环境变量配置一次理清2.1 Maven 版本怎么选别一上来就追最新版先回答一个很实际的问题下载哪个版本Maven 官网会同时提供多个版本当前主流的稳定版本大概在 3.8.x 到 3.9.x网上也能看到 3.6.3 的下载地址。我的建议是选 3.8.x 或 3.9.x 的稳定版不太建议新项目直接用 Maven 4.x——倒不是说它不能用而是很多 IDE 插件、旧项目的构建插件对 4.x 的兼容性还没有完全跟上没必要给自己挖坑。版本和 JDK 的对应关系简单整理了个表JDK 版本推荐的 Maven 版本备注JDK 8Maven 3.6.x / 3.8.x经典组合企业中大量存留JDK 11Maven 3.6.x / 3.8.x老项目升级常用JDK 17Maven 3.8.x / 3.9.x17 是当前很多新项目的选择JDK 21Maven 3.9.x较新 LTS建议 Maven 跟随新版本注意一个细节下载页面会有apache-maven-3.9.x-bin.tar.gz和apache-maven-3.9.x-src.tar.gz两种包。选 bin 那个src 是源码包普通使用不需要。2.2 Windows 和 Mac 的安装步骤环境变量到底该怎么配Windows 上安装 Maven 很简单核心三步把下载的压缩包解压到一个固定目录比如D:\apache-maven-3.9.6。路径里不要有中文和空格这是老生常谈但值得强调。新建系统环境变量MAVEN_HOME值指向解压目录。在Path变量里新增一行%MAVEN_HOME%\bin。打开新终端输入mvn -v看到输出里的Apache Maven和 Java 版本信息就说明安装成功了。Mac 上更省事用 Homebrew 一条命令就能搞定brew install maven如果你习惯手动安装也可以解压到/usr/local或家目录然后在~/.bash_profile或~/.zshrc里加export M2_HOME/Users/yourname/apache-maven-3.9.6 export PATH$M2_HOME/bin:$PATH改完记得执行source ~/.zshrc或source ~/.bash_profile让其生效。这一步很多新手会忘输入mvn -v提示找不到命令多半就是没 source。2.3 第一次运行本地仓库和 settings.xml 的正确认知装好 Maven 后我建议你立刻跑一条命令mvn help:system这条命令会触发 Maven 下载一堆基础插件下载到哪里呢默认是用户目录下的.m2/repository这个目录就是本地仓库。你可以把本地仓库想象成一个缓存区所有依赖先在这里查找找不到才去远程下载。你可能会问.m2目录里没看到 settings.xml 文件是不是装错了不是这非常正常。用户级的settings.xml是一个可选配置文件Maven 自带一套默认配置内部叫超级 POM没有用户级 settings.xml 时它照样能跑。只有你想修改默认行为——比如指定本地仓库位置、配置阿里云镜像、连接私有仓库时——才需要手动创建这个文件。如果你想知道当前 Maven 到底用了哪些生效配置可以直接用mvn help:effective-settings它会打印出合并后的最终配置包括本地仓库路径、镜像列表、代理信息。排查“为什么我改了 settings.xml 却不生效”这个问题时这条命令是神器。3. 用 IDEA 创建 Maven 项目从 New Project 到 Hello World一步步看3.1 新建 Project那些让人懵圈的字段分别是什么意思我以 IDEA 2024/2025 版的操作为例步骤基本一致。打开 IDEA选择New Project左侧选择Maven有些新版界面上叫Build Tool: Maven。然后你会看到几个需要填写的字段。Name项目名称一般也是模块名。Location项目存放路径。GroupId组织标识。通常填公司或组织的域名反写比如com.example。它决定了你项目坐标的第一个层级。ArtifactId项目标识。一般填项目名比如demo-project。它对应最终生成的 jar 包名前缀。Version版本号。开发阶段通常填1.0-SNAPSHOTSNAPSHOT 表示快照版。很多教程里会建议勾选某个archetype骨架模板比如maven-archetype-quickstart。我的建议是新手阶段不要勾任何 archetype直接创建一个最干净的空项目。因为 archetype 模板会生成一些你可能用不到的文件干扰理解。空项目自动生成的 pom.xml 非常干净适合一点点往里加内容。3.2 标准目录结构和第一个 Java 类项目创建完成后你会看到 IDEA 自动生成这样的目录结构demo-project/ ├── pom.xml └── src/ ├── main/ │ ├── java/ │ └── resources/ └── test/ ├── java/ └── resources/这个结构请务必记牢。src/main/java放正式代码src/main/resources放配置文件src/test/java放单元测试。Maven 编译、打包时都按照这套规则来找文件目录放错代码写得再好也进不了最终产物。接下来在src/main/java下新建一个包比如com.example再创建一个测试类package com.example; public class Hello { public static void main(String[] args) { System.out.println(Hello Maven); } }直接右键运行这个 main 方法看到输出后说明你的 JDK 和编译环境已经通了。但注意这里跑的是 IDEA 自己的编译还没经过 Maven。想确认 Maven 编译正常可以打开 IDEA 右侧的 Maven 工具窗口在Lifecycle列表里双击compile。完成后去target/classes目录看一眼你会发现编译出来的.class文件老老实实躺在那里。3.3 IDEA 里的 Maven 配置别让默认值坑了你IDE 有自带的 Maven但生产环境建议指到你命令行里安装的那套这样两边行为完全一致。打开Settings - Build, Execution, Deployment - Build Tools - Maven注意三个字段Maven home path填你安装的 Maven 路径比如D:\apache-maven-3.9.6。User settings file指定 settings.xml 路径。可以选 Maven 安装目录conf/settings.xml也可以选用户级~/.m2/settings.xml。填了之后 IDEA 会读取这个文件里的镜像、本地仓库配置。Local repository本地仓库路径。如果你在 settings.xml 里配了localRepository这里通常会自动读取并同步显示。这三项一定要保持一致否则会出现“命令行能下载依赖IDEA 里却报红”的诡异情况。IDEA 右侧那个 Maven 工具窗口需要认识一下。它分为几个模块Lifecycle生命周期命令、Plugins插件、Dependencies依赖列表。在Lifecycle里双击packageMaven 就会编译、跑测试并产出 jar 包产物在target/目录下。这里补充一个非常容易踩的坑如果你的项目是 Spring Boot 项目直接用mvn package打出的 jar可能无法用java -jar直接运行因为普通 package 打出的 jar 不会把项目依赖打包进去。必须额外配置 Spring Boot 的打包插件spring-boot-maven-plugin它会生成一个可执行 fat jar。这个后面讲 pom 配置时会说到。4. pom.xml 的依赖管理逻辑坐标、scope、parent 这些必须弄明白4.1 坐标与依赖传递为什么只加一个依赖却下载了几十个 jarpom.xml 是 Maven 项目的核心文件所有依赖都在这里声明。举个例子dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependencygroupId是组织坐标artifactId是模块坐标version是版本坐标。三项合起来Maven 就能在仓库中唯一定位到一个 jar。本地仓库里的目录结构其实也是按坐标路径放的比如org/springframework/boot/spring-boot-starter-web/所以坐标写错哪怕一个字母下载路径就完全对不上。依赖传递是 Maven 里最容易产生困惑的机制。你引入spring-boot-starter-web它会自动携带spring-webmvc、jackson-databind等间接依赖。这些间接依赖有自己的版本号当多个依赖都牵涉到同一个库且版本不一致时就会产生依赖冲突。排查依赖冲突的标准姿势是用mvn dependency:treemvn dependency:tree输出里会以树形结构展示整个依赖图谱谁的依赖是谁引出来的一目了然。Maven 处理冲突有一个默认规则路径越短越优先路径相同先声明的优先。这个规则偶尔会把正确的版本覆盖掉到这种时候通常就要显式声明需要的版本号来“纠正”冲突。4.2 parent 与统一版本管理别再一个版本号写十遍当一个项目里有多个模块或者你希望所有子项目统一使用某个框架版本最好的做法是引入 parent 机制。Spring Boot 项目最典型parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent继承这个 parent 之后你的 pom 里引入各种spring-boot-starter-*依赖时可以不写版本号由 parent 统一管理。这个机制的核心是dependencyManagement——父 POM 里声明了依赖版本子模块只负责引用不负责写版本。如果你的项目不想继承 Spring Boot 的 parent也可以自己在dependencyManagement里管理版本properties spring.boot.version2.7.18/spring.boot.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring.boot.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement多模块项目里父模块的packaging会设成pom表示它只是一个聚合模块不产出 jar。子模块之间如果需要互相依赖直接按坐标引用即可。4.3 scope 的作用搞清楚依赖到底要不要打进 jarpom.xml 里每个依赖都可以配置scope新手经常忽略它结果打包后 jar 体积失控或者运行时报错。几种 scope 的适用场景scope什么时候用是否打进最终产物compile默认值业务代码直接使用的依赖比如 Spring MVC会provided编译时需要但运行环境已经自带比如 servlet-api、lombok不会runtime编译期用不到运行期才需要比如 MySQL 驱动会test只在测试代码里用比如 JUnit不会最经典的是 servlet-api你的代码编译时要用到HttpServletRequest但部署到 Tomcat 后 Tomcat 自带这个 jar如果打进去反而会和容器冲突。所以要用provided。JDBC 驱动就是另一个例子。代码里用的是java.sql.DriverManager接口本身是 JDK 的只有运行时才需要连接到 MySQL 驱动实现所以可以用runtime来声明。4.4 一段可以直接抄的完整 pomb 示例我给一个新手最常遇到的“Spring Boot Web 项目”最小配置?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 parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIddemo-project/artifactId version1.0-SNAPSHOT/version namedemo-project/name properties java.version8/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这个配置里spring-boot-maven-plugin就是前面说的“打可执行 jar 的关键”。没有它mvn package只会打一个普通 jar里面只有项目自己的类没有依赖有了它才会把依赖和启动器一起打包java -jar才能直接启动。5. 镜像仓库配置与依赖加速阿里云、多镜像、deploy 发布这些都要说5.1 Maven 默认仓库太慢在 settings.xml 里配阿里云镜像Maven 默认从中央仓库repo.maven.apache.org下载依赖这个仓库服务器在海外国内访问速度经常不理想尤其是下午到晚间高峰期。解决办法是配置镜像仓库把“所有依赖都先去镜像站拉”的规则写在 settings.xml 里。在用户级~/.m2/settings.xml中配置没有这个文件就新建一个核心片段如下settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepositoryD:/maven-repository/localRepository mirrors mirror idaliyunmaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*/mirrorOf /mirror /mirrors /settings这段配置做了两件事第一把本地仓库改到了D:/maven-repository避免 C 盘越积越大第二配置一个mirrorOf为*的阿里云镜像意思是“所有仓库的请求都走阿里云”。这里要特别提醒maven.aliyun.com/repository/public是一个聚合仓库里面同时代理了中央仓库、spring 仓库、jboss 仓库等常用仓库。对绝大多数项目来说这一个镜像就够了。配置完记得在 IDEA 的 Maven 设置里把User settings file指到这个文件然后执行Reload All Maven Projects让配置重新加载。如果改了没反应先跑一下mvn help:effective-settings看看镜像到底有没有生效。5.2 多个镜像怎么配mirrorOf 的坑千万别踩有些人配了多个镜像比如阿里云一个、华为云一个、腾讯云一个心想“这个挂了还能用那个”。但 Maven 的 mirror 匹配机制和直觉不太一样它按声明顺序找到第一个匹配的 mirror 就直接使用不会因为下载失败就自动切换到下一个。所以多个 mirror 的mirrorOf不要都写成*那样基本只有一个生效。正确的做法是区分用途一个专属镜像用来加速中央仓库mirrorOf设为central。某些特殊依赖走专用仓库通过repositories节点指定而不是靠 mirror 拦截。需要动态切换镜像时用 profile 打包不同 settings而不是在一个 settings 里堆一堆 mirror。示例只想加速中央仓库同时保留其他仓库原样访问mirror idaliyun-central/id namealiyun central/name urlhttps://maven.aliyun.com/repository/central/url mirrorOfcentral/mirrorOf /mirror如果你在公司内网使用还要注意公司可能自建了私有仓库Nexus 或 Artifactory这时候正确姿势是把私服地址配成中央仓库的镜像或者通过repositories指向私服让 Maven 优先从私服拉取。私服里有就缓存给团队成员没有再去远程拉这样既能加速又能做统一管控。5.3 怎么把项目发布到远程仓库mvn deploy 的完整设置当你需要把打好的 jar 分享给其他团队使用时最简单的方式是执行mvn deploy把构件部署到远程仓库。这个远程仓库可以是公司私服也可以是云厂商的制品仓库。先在 pom.xml 里配置发布地址distributionManagement repository idreleases/id nameRelease Repository/name urlhttp://nexus.example.com/repository/maven-releases//url /repository snapshotRepository idsnapshots/id nameSnapshot Repository/name urlhttp://nexus.example.com/repository/maven-snapshots//url /snapshotRepository /distributionManagement注意id要和 settings.xml 中的server的id对应。如果私服需要账号认证在用户级 settings.xml 中加入servers server idreleases/id usernamedeploy-user/username passworddeploy-password/password /server server idsnapshots/id usernamedeploy-user/username passworddeploy-password/password /server /servers然后执行mvn deployMaven 会根据当前项目的 version 后缀自动判断发布到哪个仓库1.0-SNAPSHOT会进快照仓库1.0.RELEASE会进正式发布仓库。快照版本最显著特点是“可以重复发布同一个版本”别人再次构建时可能会拉到更新的内容正式版本则是发布后不再变化的稳定版本。6. 高频踩坑依赖报错、settings.xml 缺失、Maven 工具栏消失一次讲透6.1 依赖突然标红、报 “Download from maven failed” 的完整排查链路这个坑我相信 80% 的 Maven 用户都踩过pom.xml 里某个依赖标红或者 IDEA 底部弹出Download from maven failed。我见到最离谱的一次是有人把spring-boot.version写成了2.13.0——这个版本根本不存在坐标错得离谱IDE 当然找不到。遇到依赖报错不要急着删.m2目录按下面顺序排查。第一步确认坐标。打开 Maven 中央仓库网站或阿里云仓库网页版搜一下你写的groupId : artifactId : version组合到底存不存在。版本号写错、字母大小写写错是最常见原因。第二步看 Maven 是否处于离线模式。IDEA 的 Maven 设置里有一个Offline work开关新手有时误点开之后所有依赖都不再联网下载只能搜本地仓库。本地仓库里没有就直接报 red。检查这个开关是否关闭。第三步看本地仓库里有没有*.lastUpdated文件。Maven 下载依赖失败时会在本地仓库留下这种临时标记文件。下次想重新下载必须先把这些失败标记清理掉。可以精确删除对应依赖目录# 比如删除 spring-boot 相关失败缓存 rm -rf ~/.m2/repository/org/springframework/boot然后再执行mvn clean install --update-snapshots或者直接在 IDEA 里点击Reload All Maven Projects强制重新解析。第四步看 IDEA 使用的 settings.xml 和你命令行里的是不是同一个。很多人设置里指了 A 文件命令行默认用的是 B 文件两边配置不一致就会出现“命令行能下成功IDEA 里一直报失败”。这套排查链路走下来90% 的依赖报错都能解决。6.2 .m2 目录里没有 settings.xml 到底要不要新建“我的.m2目录下没有 settings.xml 文件是不是环境坏了”——这个问题我在各大技术社区见过无数次。答案是没有 settings.xml 完全正常它不是 Maven 的必需文件。Maven 在没有用户级 settings.xml 时会使用安装目录conf/settings.xml作为全局配置如果全局配置也没有改过那就走默认中央仓库。所以你不建任何 settings.xmlMaven 一样可以工作。只有出现以下需求时才需要新建想指定本地仓库位置想配置阿里云镜像或私有仓库需要为特定仓库配置账号认证想统一设置 JDK 编译版本。新建用户级 settings.xml 时放在~/.m2/settings.xml即可。最简模板settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepository${user.home}/.m2/repository/localRepository mirrors mirror idaliyunmaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*/mirrorOf /mirror /mirrors /settings改完之后同样去检查mvn help:effective-settings确认mirrors节点里确实有你的配置。如果仍然走默认仓库大概率是你把文件名搞错了比如写成了settings.xml.txtWindows 默认隐藏扩展名时很容易犯这个错。6.3 IDEA Maven 工具栏不见了、项目识别不了怎么治有一个很日常却很烦人的状况打开项目后发现右侧没有 Maven 工具窗口或者 IDEA 提示“不是 Maven 项目”。处理顺序我建议按“轻”到“重”来。第一个办法看窗口是不是被折叠了。IDEA 的新版界面所有侧边栏都可以手动收起右侧如果只有一个小竖条点一下展开Maven面板就行。路径是View - Tool Windows - Maven。第二个办法手动把项目关联为 Maven 项目。在项目里找到pom.xml右键选择Add as Maven ProjectIDEA 会重新识别这个项目结构。第三个办法关闭项目后删除.idea目录再重新打开项目。.idea目录是 IDEA 的项目配置缓存里面如果存了错误的项目识别信息会导致项目一直不被当 Maven 看待。删除后重新导入IDEA 会从零解析 pom.xml。看到 Maven 面板了但Lifecycle下面没有命令也可以执行右侧工具栏里的刷新按钮Reload All Maven Projects触发一次重新加载。还有一种情况是 IDEA 版本升级后老项目里的.idea配置和新版本冲突删掉重来往往就好了。6.4 几个“小毛病”的补救JavaFX 项目、旧系统、中文路径最后补充几个小场景。JavaFX 项目加 Maven 配置核心依赖是javafx-controls和javafx-fxml并且注意要给 Maven 编译插件指定 JDK 模块参数。如果 JDK 17 以上还需要配置maven-compiler-plugin并加入--add-exports之类的参数否则编译时会发生模块访问报错。老系统比如 Windows 7装 Maven先确认系统能装哪个版本的 JDK。Windows 7 自带或能装的一般是 JDK 8对应 Maven 3.6.x 最稳。太新的 Maven 版本可能因为 TLS 加密协议问题连不上中央仓库——这不是 Maven 有毛病而是老系统底层网络组件太旧换 3.6.x 通常能避开这个坑。安装路径含中文和空格会导致 Maven 在解析某些插件路径时出现诡异错误。一开始就把路径定在纯英文、无空白的目录下能省掉很多莫名其妙的麻烦。这个建议听起来很老土但在实际项目中踩中的人真的很多。说到打包如果你只是想快速生成一个可执行 jar 交差自己看一眼项目里有没有spring-boot-maven-plugin没有的话打出来的 jar 跑不起来别奇怪。普通库项目的 jar 是给别的项目依赖用的Spring Boot 项目的可执行 jar 是给java -jar用的这两种诉求对应的构建插件完全不同搞清楚自己想要哪一种再决定配不配插件。做 Maven 配置这件事我个人这几年最大的体会是能用最小配置跑通的东西就不要上来堆一大套。很多新人喜欢在网上找一份“全家桶”settings.xml 直接复制粘贴结果镜像配了四五个、仓库写了一大堆、还带了各种奇怪的 plugin 配置出了问题连是哪一层导致的都分不清。我自己的习惯是分步走先保证一条mvn -v能正常跑再保证mvn clean install能通最后才逐步加镜像、加仓库、加认证。每一步都通过命令行确认结果再回 IDEA 里做同样验证。Maven 不是那种“配置越复杂越专业”的工具它的价值恰恰在确定性——目录结构对了、坐标写对了、仓库配置对了剩下的事它替你搞定。把这个确定性建立起来后面再复杂的多模块工程、持续集成、制品发布都是在同一套逻辑上做加法而已。