Maven 这个词做 Java 的人几乎天天见但真要把它讲清楚我通常会从一句话开场Maven 是 Java 项目的依赖管理工具也是标准化的构建工具。如果你还在靠手工复制 jar 包维护项目或者被“本地编译好好的一打包就缺类”“同事电脑能跑我这死活不行”“版本用错笑得停不下来”这类问题折腾过那这篇内容就是给你准备的。这篇我会把 Maven 从安装配置、settings.xml、pom.xml 编写、命令行操作到 IDEA / Eclipse / VSCode 集成完整走一遍最后附上我实际踩过的坑和排查套路。新手看完全能上手老手可以直接跳到 3、4、6 章对一下自己的配置习惯顺便看看有没有忽略的细节。1. Maven 到底是什么为什么要用它先说个最直观的场景。刚入行那会儿我做项目还要去搜索引擎找某个 jar 的下载地址然后解压、复制粘贴到lib目录再手动加入 Build Path。这种“jar 包地狱”到现在依然是很多团队痛苦的来源。1.1 从 jar 包地狱聊起你需要的依赖不是孤立的。用 Spring 就要连带引入 Spring Core、Spring Context、commons-logging、javax.annotation 等一堆间接依赖用 MyBatis 又得带 jdbc 驱动和日志包。这些依赖之间还有版本兼容问题A 库要 logging 1.2B 库要 logging 1.3塞进同一个 classpath 就可能冲突。手动管理 jar 的麻烦是连锁的依赖传递靠手查你要一个个点进去看它依赖了谁然后全部下下来。版本不统一每个人从网上找的版本可能不同出现“我这边能跑、你那边不行”。构建动作不标准有人用 eclipse 直接 export有人写 ant 脚本编译打包流程五花八门。仓库混乱公司内同一个 jar 的旧版本、新版本散落各处没有统一出处。1.2 Maven 解决的三个核心问题Maven 做的事情其实非常聚焦第一依赖管理。你在pom.xml里声明一个依赖坐标Maven 自动从仓库下载它并且把它声明的依赖也一并下载。这套传递机制把“手动找出所有间接 jar”这个环节彻底自动化了。第二标准化构建。Maven 定义了一套统一的生命周期编译、测试、打包、部署都是同一套命令。新同事入职不用去背项目文档里那套自定义脚本mvn clean install一条命令走天下。第三项目约定。Maven 强制了目录结构源码放src/main/java测试代码放src/test/java资源放src/main/resources输出在target。不同项目之间的结构完全一致维护成本肉眼可见地降低。1.3 入门前必须理解坐标、仓库、生命周期这三个概念是 Maven 的根基我尽量用生活化方式说。坐标Coordinates就像快递的收货地址。每个构件有一个唯一坐标属性作用类比groupId组织 / 项目组标识快递公司的省市区artifactId项目 / 模块名称小区名version版本号门牌号packaging打包类型默认 jar包裹类型仓库Repository是存“包”的地方。Maven 会先去本地仓库找找不到就去远程仓库下载。本地仓库默认在用户目录下的.m2/repository这个目录就是你机器上所有项目的依赖缓存。生命周期Lifecycle是构建阶段的顺序嵌套。先compile才能test先test才能package。执行后面的命令前面的阶段会自动执行不需要一条条命令去敲。理解了这三个词后面所有内容都是在此基础上展开的。2. 环境准备与安装让 Maven 在各平台跑起来很多人卡在安装不是因为不会解压而是因为版本配对出了问题。2.1 安装前的版本选择JDK 对不上才是最坑的Maven 是 Java 程序安装它之前必须先有 JDK且版本必须匹配。这些年踩过不少新同事的坑JDK 17 配 Maven 3.5.2 直接报UnsupportedClassVersionError就是因为老版本 Maven 的字节码级别跟不上新 JDK。官方对版支持大概是这样Maven 版本要求 JDK我的使用建议3.6.x 及以前JDK 7 / 8不推荐新项目使用3.8.xJDK 8 及以上兼容老项目时推荐3.9.xJDK 8 及以上当前稳定首选4.xJDK 17 及以上新特性尝鲜可选注意如果你下载的是 Maven 3.6.3配 JDK 17大概率会遇到兼容性问题。别纠结网上那些 3.6.1 / 3.6.3 教程新项目直接用 3.9.x 更省心。旧版本虽然能在 Apache Archive 仓库找到但不建议为了“老教程熟悉”去迁就。2.2 Windows 安装与配置环境变量Windows 安装 Maven 很简单但细节决定成败。到 Apache Maven 官网下载二进制压缩包apache-maven-3.9.x-bin.zip。解压到不含空格和中文的路径比如D:\dev\apache-maven-3.9.9。新建系统环境变量MAVEN_HOME值就是解压路径。早期教程喜欢配M2_HOME现在用MAVEN_HOME更规范Maven 自己也不认M2_HOME了。编辑Path变量新增%MAVEN_HOME%\bin。打开新终端输入mvn -v验证。PowerShell 用户也可以临时设置# 仅当前终端生效 $env:MAVEN_HOME D:\dev\apache-maven-3.9.9 $env:Path ;$env:MAVEN_HOME\bin配置完必须新开终端窗口因为环境变量在当前进程里不会自动刷新。2.3 macOS 与 Linux 安装macOS 最省事的方式是 Homebrewbrew install maven mvn -v但国内网络环境Homebrew 下载有时会让你等到怀疑人生。手动安装则更可控curl -O https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz tar -xzf apache-maven-3.9.9-bin.tar.gz sudo mv apache-maven-3.9.9 /opt/maven然后编辑/etc/profile或用户目录的~/.zshrcexport MAVEN_HOME/opt/maven export PATH$MAVEN_HOME/bin:$PATHLinux 服务器同样用上面这套流程。注意别下载-src.zip那个包那是源码包拿到手你还得自己编译浪费时间。一定要认准bin字样。2.4 验证安装mvn -v 到底在输出什么输入mvn -v输出可能长这样Apache Maven 3.9.9 (8e6f0e2a8c9d3a6e4f2b6a7e8c9d0e1f2a3b4c5d) Maven home: /opt/maven Java version: 17.0.11, vendor: Eclipse Adoptium, runtime: /usr/local/jdk-17 Default locale: zh_CN, platform encoding: UTF-8重点看三处Maven 版本确认是自己装的版本。Java version确认 Maven 用的 JDK 是哪个。这里经常出现which java指向的路径和JAVA_HOME不一致的问题导致 Maven 用了旧 JDK。platform encodingWindows 上如果显示GBK后续源码里有中文注释或资源文件时读文件可能出现乱码。建议统一 UTF-8后面的编译配置里也要强制指定encodingUTF-8/encoding。3. settings.xml 是配置的枢纽本地仓库、镜像与私服Maven 装完只是第一步真正决定你“下载体验”的是配置文件settings.xml。群里天天有人问“为什么依赖下载这么慢”“为什么一直报错”八成问题出在这个文件上。3.1 全局配置与用户配置先搞清楚改的是谁Maven 安装目录下的conf/settings.xml是全局限定配置影响这台机器上所有用户用户目录~/.m2/settings.xml是当前用户配置优先级更高。两者同时存在时相同配置项以用户配置为准。我习惯把所有自定义都放在~/.m2/settings.xml因为避免污染全局文件、方便迁移。你换电脑时把这个文件拷走仓库路径、私服账号全带走了。3.2 本地仓库位置的作用与修改默认本地仓库位置是~/.m2/repository。问题在于C 盘空间紧张、项目文件拷到新机器、公司统一要求使用共享仓库路径……这时候就要改默认位置。settings localRepositoryD:/maven/repository/localRepository /settings注意不要放在项目里面。本地仓库理论上是全机共享的依赖缓存塞进项目目录会导致每个项目都重新下一套依赖而且.gitignore处理起来很麻烦。3.3 配置国内镜像仓库用阿里云镜像讲透原理依赖下载慢根源是中心仓库服务器在国外网络访问不稳定。解决办法不是换 JDK也不是反复删库重下而是配置镜像仓库。国内最常用的就是阿里云 Maven 镜像。在settings.xml的mirrors节点里加mirror idaliyun/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror原理拆开来看mirrorOfcentral/mirrorOf表示只拦截central这个仓库。Maven 默认使用中央仓库central所有依赖都先去中央仓库找但因为我们声明了镜像Maven 会把对central的请求转发给镜像地址。阿里云的public仓库其实是一个聚合地址里面同时代理了 central、jcenter、google 等多套仓库所以日常依赖基本够用。阿里云还提供了一系列独立仓库比如spring、gradle-plugin、public、releases、snapshots有特殊需求时可以按需添加。3.4 多镜像轮询配置与优先级只配一个镜像万一这个镜像挂了或没有某个构件构建就直接挂掉。所以我建议配置多个镜像做兜底。mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror mirror idtencent/id mirrorOfcentral/mirrorOf urlhttps://mirrors.cloud.tencent.com/nexus/repository/maven-public//url /mirror /mirrors这里有几个细节务必要知道镜像不是集群负载均衡。Maven 的镜像规则是匹配某个仓库的镜像如果有多个选择第一个可用的而不是自动切换。mirrorOfcentral/mirrorOf同时匹配两个镜像时Maven 会取第一个第一个失败才会尝试下一个吗实际上Maven 对镜像选择是先挑出匹配的镜像按声明顺序选择第一个如果这个镜像下载失败它并不会自动 fallback 到第二个镜像。所以写多个mirrorOfcentral/mirrorOf对这种需求意义有限。想要实现 fallback更靠谱的做法是在 POM 或仓库配置里加repositories或者将镜像的mirrorOf写得更具体。更常见的企业方案是直接连公司 Nexus 私服把私服作为统一入口。3.5 server 认证、profile 等高频配置项需要认证的私服光有 mirror 还不够。Maven 要求用户名密码写在settings.xml的servers里不能写进pom.xmlserver idcompany-nexus/id usernameyour-name/username passwordyour-password/password /server注意这个id必须和pom.xml里repository/snapshotRepository的 id 保持一致Maven 才能对上号。profiles节点常用来做环境切换。比如项目需要 JDK 版本、资源定义等按 profile 区分。不过个人项目通常用不到复杂的 profile了解即可。4. 创建项目、写 pom.xml、跑生命周期命令安装配好接下来就是真正用起来了。这一章我会从一个空目录开始把项目建起来并完整跑一遍构建。4.1 命令行创建项目archetype 与 Maven 3.9 的新方式传统方式是用 archetype 模板生成mvn archetype:generate -DgroupIdcom.example -DartifactIddemo -DarchetypeArtifactIdmaven-archetype-quickstart这命令会卡在那等你去选模板编号还要下载一堆元数据。新版本更推荐直接用mvn archetype:generate的简化形式不过我还是更喜欢在 IDEA 里创建手速更快。如果你想体验纯命令行极简方式可以直接手写目录demo ├── pom.xml └── src ├── main │ ├── java │ └── resources └── test └── java然后再写个最简单的pom.xml这也完全没有问题。Maven 的目录约定并不强制通过 archetype 生成你手动建目录只需要符合约定即可。4.2 pom.xml 核心结构坐标、依赖、构建一个最小可运行的 pom 长这样project modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIddemo/artifactId version1.0.0/version packagingjar/packaging properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version5.10.2/version scopetest/scope /dependency /dependencies /project注意modelVersion固定写4.0.0这是 Maven POM 模型的版本号不是项目的版本别乱改。properties里的maven.compiler.source和target分别控制 Java 源码版本和编译目标字节码版本。这一步非常关键很多人编译报invalid target release就是因为这个和 JDK 版本不匹配。4.3 依赖管理进阶scope、属性、排除与传递依赖依赖不只是声明坐标scope决定依赖的可见范围和使用时机scope作用compile默认编译、测试、打包都包含provided编译期需要运行期由容器提供比如 servlet-apiruntime编译不需要运行需要比如 JDBC 驱动test只在测试编译和运行时使用JUnit 最典型system本地 jar配合 systemPath不推荐import只在 dependencyManagement 中使用用于导入 BOM举个例子你写 Spring Boot 应用运行有内嵌 Tomcat 所以 Servlet API 不需要打进包里写测试用 JUnit测试代码显然不能进最终 jar。这些用scope就能精确控制。依赖冲突是比 scope 更头疼的问题。项目里出现两个版本的同款 jar 时Maven 默认采用“最短路径优先声明顺序优先”的策略。真要精确排除某个传递依赖用exclusionsdependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.14/version exclusions exclusion groupIdcommons-logging/groupId artifactIdcommons-logging/artifactId /exclusion /exclusions /dependency4.4 生命周期与常用命令clean、compile、test、package、install、deployMaven 生命周期分三套最常用的是default生命周期运行时按顺序执行各个阶段。我常和新人说先把这几个命令背熟mvn clean # 删除 target 目录 mvn compile # 编译主代码到 target/classes mvn test # 运行测试默认先 compile mvn package # 打包产出 jar/war 到 target mvn install # 打包并安装到本地仓库供其他模块引用 mvn deploy # 部署到远程仓库私服 mvn clean install # 最常用组合清理后完整构建附带的参数也很关键mvn clean install -DskipTests # 跳过测试编译和执行 mvn clean install -Dmaven.test.skiptrue # 彻底跳过测试相关的一切 mvn clean install -U # 强制刷新远程仓库的 SNAPSHOT 依赖 mvn compile -o # 离线模式依赖必须已在本地4.5 跑一次 mvn clean install观察构建过程一条命令跑完控制台输出里能看到依赖下载、插件执行、测试报告、打包路径。这就是 Maven 在告诉你它干了什么。构建成功的最后几行通常是这样[INFO] --- maven-jar-plugin:3.4.1:jar (default-jar) demo --- [INFO] Building jar: /path/to/demo/target/demo-1.0.0.jar [INFO] BUILD SUCCESS如果构建失败重点看[ERROR]下面的内容。最常见的失败原因是依赖解析失败、测试不过、编译报错。别急着百度整段报错先看是发生在哪个阶段问题就缩小一大半了。5. IDE 集成IDEA、Eclipse、VSCode 里的 Maven命令行走通的下一步是让 IDE 和 Maven 协作。很多新手被“IDEA 里明明配置了为什么下载依赖还是用默认设置”这个问题卡住这里我讲透。5.1 IDEA 里设置默认 Maven 配置新建项目不用再改IDEA 自带了一个 Maven但版本通常不是我想要的所以要做全局配置。打开Settings / Preferences→Build, Execution, Deployment→Build Tools→MavenMaven home path选择你安装的 Maven 目录不要选 IDEA 自带的。User settings file选择~/.m2/settings.xml。Local repository一般会自动根据 settings.xml 读取不需要手动填但显示不对时可以直接指定。最关键的技巧把这些配置设成默认配置。新版 IDEA 在Settings / Preferences→Build, Execution, Deployment→Build Tools→Maven里修改后对当前项目生效但新建项目还会回到默认。你需要点开左侧的Settings设置齿轮旁边有个用户设置图标或者直接在New Projects Settings里设置Settings for New Projects。更粗暴的替代方案是在全局设置里把User settings file和Maven home path填好让新建项目都继承这一套。5.2 Eclipse 配置 MavenMaven 插件已内置Eclipse 从较新版本开始已经自带 m2e 插件。在Window→Preferences→Maven→Installations里点击Add选择你本机 Maven 目录勾选 Apply。再切到Maven→User Settings填入 settings.xml 路径全局这块就配好了。Eclipse 容易踩坑的一个点是项目右键Maven→Update Project快捷键AltF5到底有什么用。它不光是刷新依赖还会重新解析 POM、同步依赖树。改完 pom.xml 后 IDE 没有自动更新时手动跑一次这个操作基本能解决 90% 的红色报错。5.3 VSCode 配置 Maven 项目VSCode 本身不是 Java IDE要靠扩展。装两样东西Extension Pack for Java微软官方那套Maven for Java红帽的 maven 扩展这两个扩展装完VSCode 会自动识别当前工作区里的pom.xml文件界面左侧会出现 MAVEN 面板能看到依赖树、插件目标还能直接双击运行生命周期阶段。VSCode 里 Maven 使用的配置文件默认也走~/.m2/settings.xml没有单独的配置入口。想改本地仓库路径依然是改 settings.xml不需要在 VSCode 里额外设。5.4 本地仓库/repository 在 IDE 里到底在哪这个问题常被问到尤其是用了新 IDE 之后。答案是所有 IDE 的 Maven 本地仓库路径都来自同一份 settings.xml除非 IDE 里单独覆盖了 Local repository 字段。比如我用 Trae、JetBrains 系工具打开Maven设置都能看到Local repository路径默认跟随 settings.xml。如果你把本地仓库挪到了 D 盘仍然提示下载依赖先回 IDE 配置里确认是不是覆盖成了默认路径。实操心得我建议所有 IDE 的 Maven 设置都指向同一份 Maven 和 settings.xml这样无论用哪个 IDE 打开项目依赖缓存和仓库配置完全一致不会出现“IDEA 里好好的Eclipse 里全部标红”的诡异现象。6. 常见问题排查与避坑实录这一章我把平时群聊里反复出现的问题一次性整理完。每一条都是我真实跑过的场景。6.1 依赖报错 red 且 Failed to read artifact descriptorIDEA 的 Maven 面板里依赖标红控制台报Failed to read artifact descriptor for xxx:jar。这通常不是代码问题而是本地仓库里的对应坐标损坏。排查步骤先去本地仓库~/.m2/repository找到对应目录看看是不是只有*.lastUpdated结尾的文件没有正常 jar。如果有.lastUpdated说明上次下载没成功留下了一个失败标记Maven 看到这个标记会认为已经尝试过短期内不会重试。解决方式删除对应目录下的.lastUpdated文件再重新构建。更省事的做法是配置强制更新mvn clean install -U仍不行就换镜像或确认依赖是否存在于目标仓库。6.2 依赖下载一半就失败本地仓库被 lastUpdated 污染这是国内用户高发问题。网络波动导致 jar 只下了一半但是仓库里留下了一个带.part或者.lastUpdated的残留。Maven 不会自动修复只会反复在那干等。我提供一个手工清理命令Windows 和 macOS / Linux 分别执行# macOS / Linux find ~/.m2/repository -name *.lastUpdated -delete# Windows PowerShell Get-ChildItem -Recurse -Path $HOME\.m2\repository -Filter *.lastUpdated | Remove-Item清理后重新构建。如果问题反复出现多半是镜像本身不稳定换备用镜像或直接升级到企业私服。6.3 明明换了镜像还是去中央仓库/下载慢这个问题最常见的三个原因镜像声明没生效检查镜像在哪个 settings.xml 里写的。IDEA 里选择的 User settings file 并不是你改的那个文件。依赖来自非 central 仓库有些依赖只有 JCenter 或其他 repository 有mirrorOfcentral只代理中央仓库JCenter 请求不会走这个镜像所以慢。可以在 pom 里显式声明仓库。本地仓库里有损坏标记见上面 6.2。一句话总结先确认你改的是“IDE 正在读”的 settings.xml再看依赖到底从哪个仓库解析。6.4 Linux 与信创操作系统的 Maven 安装问题含麒麟有次群里问“Maven 有麒麟版吗”我其实被问住了。Maven 是 Java 程序它被打包成 zip / tar.gz运行靠java -jar本身完全跨平台。所谓“某某系统是否支持”取决于这台机器上能不能装好 JDK。所以结论是没有专门针对麒麟系统的特供 Maven 版也不需要。你只要在这个系统上装一个对应的 JDK然后解压通用 tar.gz 包、配置环境变量就能跑。实际工作中我在国产化服务器上装 Maven 就是走的标准 Linux 流程遇到的问题只剩“默认源太老需要手动装高版本 JDK”。6.5 JavaFX 项目的 Maven 配置要点JavaFX 从 JDK 11 起被移出 JDK它作为普通依赖出现在 Maven 里。如果只添加依赖运行时可能报JavaFX runtime components are missing。需要在 pom 里加插件并在 module-info.java 中引入模块。最小配置示例plugin groupIdorg.openjfx/groupId artifactIdjavafx-maven-plugin/artifactId version0.0.8/version configuration mainClasscom.example.MainApp/mainClass /configuration /plugin然后启动命令不要用java直接mvn clean javafx:run还要注意maven.compiler.release需要和 JavaFX 版本匹配2019 年之后的 JavaFX 版本用 11 以上没问题但 JavaFX 8 依赖一类的问题就别挣扎了直接升版本。6.6 新建 Maven 项目 src 目录没生成、目录结构怪异怎么办这个问题常见于 Eclipse 或某些 IDEA 版本里创建 Maven 项目后只有src/main/resources没有src/main/java。原因一般是 IDEA/Eclipse 的模板里没有生成源码目录或者目录被系统忽略。解决办法很直白在 IDEA 里打开Project Structure→Modules找到对应模块的Sources标签把src/main/java右键标记为Sources把src/test/java标记为Test Sources。在 Eclipse 里项目右键Build Path→Configure Build Path→SourceAdd Folder 手动加上缺失的目录。然后再执行Maven→Update Project。顺便多提一句如果目录名大小写不对比如建成了src/main/java/但资源文件放在src/main/resources没被复制进 target优先看pom.xml里有没有配置resources很多时候不是目录问题而是资源过滤配置没写。最后聊两个我坚持了很久的 Maven 使用习惯。第一不管哪个项目pom.xml第一件事是统一编码和 JDK 版本source、target、release、encoding四件套写死能省掉一大批“我本地没问题”的沟通成本。第二依赖版本尽量用properties抽出来统一管理或者直接用 Spring Boot 这类 BOM 统一收口别在项目里散落十几个魔法版本号。Maven 的学习曲线其实很短它真正的门槛不在于“会装会用”而在于遇到问题时知道去哪里看本地仓库有没有settings.xml 配没配对依赖到底属于哪个仓库生命周期执行到哪一步。把这四条链路捋顺绝大多数网上求助帖里的问题你自己就能独立解决。