Maven安装配置全指南：从环境变量到IDEA集成，解决依赖管理与构建难题

1. 先弄明白Maven到底是干嘛的三个最关键的认知说实话我见过太多新手一上来就搜Maven安装教程照着步骤装完跑通了mvn -v结果过了两天还是搞不懂这个工具到底解决什么问题。如果你的目标只是照着抄能跑那这篇教程确实够用了但如果你想让Maven真正成为你的开发利器我建议先花三分钟理解它的底层逻辑。毕竟无论是Windows还是macOS无论是IntelliJ IDEA还是EclipseMaven的核心价值都不会变。很多人第一次接触Maven是因为IDEA里新建项目时有个Maven选项或者同事扔过来一个项目说你用Maven拉一下依赖。那Maven是干嘛的简单说它是一个项目管理和构建自动化工具。它的核心是三个词依赖管理、统一构建流程、约定优于配置。这三个词听起来很抽象我各用一个场景展开。先说依赖管理。Java生态里几乎每个项目都会用到第三方库比如MySQL驱动、Spring框架、JSON解析库。在没有Maven的时代你需要自己到官网把jar包一个个下载下来丢到项目的lib目录里然后手动引入到classpath。这个过程有多痛苦下载的jar包版本没对上、依赖之间互相冲突、传代码给别人时忘了带lib目录、换台电脑就得重新配置一遍。Maven用坐标groupId、artifactId、version来描述一个jar包然后在配置文件里声明依赖它会自动帮你下载并管理整个依赖树。比如你在pom.xml里写下mysql-connector-java的坐标Maven会从中央仓库拉取这个jar包还会自动拉取它依赖的其它包。再说构建流程。一个Java项目的完整生命周期包括编译、测试、打包、部署。以前这些步骤可能需要你手动执行javac、jar、复制文件等一系列命令。Maven定义了lifecycle生命周期的概念从validate到clean再到compile、test、package、install、deploy一条命令就能串联起来。比如你执行mvn clean package它就会按顺序帮你清理target目录、编译源码、运行测试如果你配置了的话、最终打出jar包或者war包。这个流程在任何机器上都是一致的不会出现我本地能跑你那儿怎么跑不了的尴尬。最后是约定优于配置。Maven默认了一套项目目录结构比如源码放在src/main/java测试代码放在src/test/java资源文件放在src/main/resources打包产物放在target目录。只要你的项目遵循这个结构Maven就能自动识别不需要额外配置。这也是为什么你看到的所有Maven项目长得都差不多——这种统一性是巨大的生产力。清楚了这三点你就能理解后续所有配置操作的目的了。比如为什么要配置环境变量因为你需要能在命令行的任意位置直接执行mvn命令而不是每次都要敲完整路径。为什么要改settings.xml因为Maven默认的中央仓库在国外下载依赖慢得让人抓狂你需要换一个国内镜像源。为什么要做IDEA集成因为你不想在命令行和IDE之间来回切换更不想让IDE用一套和命令行不一样的Maven配置。下面我们就进入正题从Windows环境开始一步步把整个链路搭好。2. Windows安装与环境变量配置版本选对了就成功一半2.1 先确认JDK版本再选Maven版本Maven本身是用Java写的所以它运行的前提是你机器上已经装好了JDK不是JRE是整个JDK。这一步看着不起眼但版本对应关系搞错了后面会踩很多坑。先说结论如果你装的是JDK 8那Maven 3.9.x可以直接用如果你装的是JDK 11或者JDK 17也建议用3.9.x或者3.8.x系列。如果你用的是JDK 21那Maven 3.9.x也没问题但3.8.x早期版本可能有些兼容性问题。总体原则是不要用太老的Maven配太新的JDK也不要拿太新的Maven配老掉牙的JDK。我整理了一个简单的版本建议表直接照着选JDK版本推荐Maven版本说明JDK 8Maven 3.6.3 ~ 3.8.8最稳妥的组合企业级老项目基本是这个搭配JDK 11Maven 3.8.x 或 3.9.x兼容性良好注意3.9.x需要JDK 8JDK 17Maven 3.9.x推荐3.9.6以上对JDK 17的模块化支持更好JDK 21Maven 3.9.6实测3.9.9没有问题怎么确认JDK版本Windows下打开命令行Win R输入cmd回车执行java -version。如果提示不是内部或外部命令说明JDK还没配好环境变量你需要先去搞定JDK再回来继续。这里多说一句我遇到过不少朋友把JDK装好后没配置JAVA_HOME导致IDEA里能用但命令行执行mvn时报错。其实Maven启动脚本里面会主动去找JAVA_HOME这个环境变量所以请务必确保你配置了它——右键此电脑-属性-高级系统设置-环境变量在系统变量里新建一个JAVA_HOME值填你的JDK安装目录比如C:\Program Files\Java\jdk-17然后在Path里加上%JAVA_HOME%\bin。2.2 下载并解压Maven安装包Maven的官方下载地址是maven.apache.org打开后找到Download页面。Windows系统不用下载apache-maven-x.y.z-bin.tar.gz而要选apache-maven-x.y.z-bin.zip。如果你用的是macOS或者Linux倒是可以用tar.gz包。下载完成后解压到你想要安装的目录。这里有个经验之谈不要解压到带空格和中文的路径下。比如C:\Program Files\Apache\Apache Maven这种虽然理论上Maven能处理但后面配置环境变量、IDEA集成时容易出幺蛾子特别是某些老版本的IDEA插件会出现路径解析问题。我习惯放在D:\dev\apache-maven-3.9.9这种纯英文路径清爽也省心。解压完成后看一下这个目录的结构。bin目录下就有核心的可执行脚本mvn.cmdconf目录下放着最重要的settings.xml配置文件lib目录则是Maven运行时依赖的各种jar包。这些先有个印象即可后面我们会逐一用到。2.3 配置MAVEN_HOME和PATH环境变量这一步是整个安装过程的核心也是很多新手最容易出错的地方。我先把操作步骤列出来再说几个容易忽略的细节。右键此电脑 - 属性 - 高级系统设置 - 环境变量。在系统变量区域点击新建变量名填MAVEN_HOME变量值填你的Maven解压目录比如D:\dev\apache-maven-3.9.9。在系统变量中找到Path双击进入编辑点击新建添加%MAVEN_HOME%\bin。点击确定保存所有窗口。这里有三点需要注意。第一MAVEN_HOME的值不要带末尾的反斜杠也就是不要写D:\dev\apache-maven-3.9.9\因为后面很多地方会拼接MAVEN_HOME和其他路径多余的斜杠可能导致问题。第二Path里加的是%MAVEN_HOME%\bin不是%MAVEN_HOME%。因为我们要的是bin目录下的mvn.cmd能直接被找到。第三配置完后一定要重新打开一个新的命令行窗口不要用之前开着的旧窗口因为环境变量的生效需要重新读取。2.4 验证安装命令行跑通mvn -v配置完成后打开一个新的cmd窗口输入mvn -v如果看到类似下面的输出说明安装成功了Apache Maven 3.9.9 (8e9479a3f1f1a2b8cec0a0e4e9c4b2a3) Maven home: D:\dev\apache-maven-3.9.9 Java version: 17.0.10, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-17 Default locale: zh_CN, platform encoding: UTF-8 OS name: windows 10, version: 10.0, arch: amd64, family: windows这几行信息很关键我一个个说。Maven home必须指向你解压的目录如果指向别处说明MAVEN_HOME可能配错了。Java version显示的是Maven使用的JDK版本它和命令行里java -version显示的一致就行。platform encoding是平台编码Windows下默认可能是GBK这个后续需要根据实际情况调整——如果你的项目源码是UTF-8编码而控制台是GBK编译时可能会报不可映射字符的错误这个我们在第五章会细聊。如果执行mvn -v提示不是内部或外部命令排查顺序是先看MAVEN_HOME是否正确再看Path里是否加了%MAVEN_HOME%\bin最后确认你是否真的重新打开了命令行窗口。这三个地方都对了基本不会出问题。2.5 让Maven用起来更顺手的其他环境变量可选配置除了MAVEN_HOME和Path还有两个环境变量不是必须的但配置了会让后续操作更顺畅算是老手的习惯。第一个是MAVEN_OPTS。这个变量用来配置Maven运行时的JVM参数比如内存大小。遇到大型项目时默认的内存可能不够会出现OutOfMemoryError。我通常会在系统变量里加上MAVEN_OPTS值设为-Xms512m -Xmx1024m -Dfile.encodingUTF-8。最后那个编码参数非常实用可以规避前面提到的控制台GBK和源码UTF-8不一致的问题,至少在命令行编译时能省下不少烦恼。第二个是MAVEN_CONFIG。它指向Maven配置的存放位置默认在用户目录下的.m2文件夹。正常情况不需要专门配置它但如果你想把.m2目录也挪到D盘有些人纠结C盘空间可以通过这个变量来修改。3. settings.xml才是后续体验的分水岭本地仓库与镜像源配置如果你以为装好了、能跑mvn -v就算大功告成那就错了。Maven真正日常打交道最多的是conf目录下的settings.xml这是我个人认为整个配置过程中最值得花时间的地方。3.1 本地仓库的默认位置与修改Maven会自动从中央仓库下载依赖jar包到你本地的本地仓库Local Repository。默认情况下本地仓库位于${user.home}/.m2/repository——也就是在C盘的用户目录下比如C:\Users\你的用户名\.m2\repository。这个默认位置有两个问题第一C盘是系统盘如果装的项目多了依赖包可能有好几个GB白白占掉了宝贵的SSD空间第二如果你经常重装系统或者重置系统残余文件.m2目录容易被清理掉导致重新下载所有依赖。所以我强烈建议把本地仓库挪到一个专门的目录比如D:\dev\maven-repository。修改方式很简单打开conf\settings.xml找到localRepository标签。它默认是被注释掉的你把它取消注释并改成自己的路径即可localRepositoryD:\dev\maven-repository/localRepository注意这个目录如果你现在还没创建Maven会在第一次使用时自动创建不需要手动建。修改完保存后可以在命令行里执行mvn help:effective-settings前提是已经配置了MAVEN_HOME看看生效后的配置是否有你设置的内容。这个命令输出比较长你只要搜索localRepository确认路径指向了D:\dev\maven-repository即可。3.2 从龟速到秒下配置阿里云镜像这是无数新手最痛的场景在pom.xml里加了个依赖然后IDEA右下角弹出Downloading...一等就是十分钟最后还可能报超时错误。原因很简单——Maven中央仓库repo.maven.apache.org部署在国外国内访问速度极不稳定。解决办法是配置国内镜像源。目前最主流的还是阿里云镜像因为我个人从2016年开始用到现在稳定性很好。在settings.xml的mirrors标签内加入如下配置mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror简单解释一下这几个标签。mirrorOf填*表示所有请求都走这个镜像url是镜像地址。阿里云公共仓库聚合了中央仓库、JCenter和Google等多个源的内容绝大多数Java库都能在这里找到。如果你的项目用到了一些特殊的公共仓库比如Spring的里程碑版本更完整的配置是再加一个镜像mirrorOf设为spring-milestones等特定id。但就大多数普通项目而言上面这一个就够用了。配置完成后可以找个带依赖的项目目录执行mvn clean compile观察日志里的下载速度。如果是从阿里云下载下载速度应该能达到几MB每秒和之前天壤之别。3.3 让Maven默认使用JDK 17profile配置一劳永逸还有一个常见的坑不同项目的pom.xml里可能会声明maven.compiler.source和maven.compiler.target用来告诉编译器源码基于哪个JDK版本。但如果你不在settings.xml里做一层兜底某些老项目或者IDEA自动生成的项目可能没有声明Maven就会使用它运行时的JDK版本去编译有时会导致bad class file或者不兼容的字节码版本错误。我习惯在settings.xml的profiles里加一个全局profile指定默认的JDK编译版本。比如我的机器是JDK 17就这样配置profile idjdk-17/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target maven.compiler.compilerVersion17/maven.compiler.compilerVersion project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /profile这样当pom.xml里没有显式指定编译版本时Maven会默认使用JDK 17的语法规则编译同时源码编码统一为UTF-8避免中文注释导致的乱码错误。3.4 顺手做两件小事Maven下载相关的优化第一件是给Maven增加下载重试参数。网络环境再稳定也有抖动的时候Maven默认对失败的下载不会自动重试多少次。你可以在settings.xml里直接加mirrors配置之外的内容吗不行重试参数其实是写在Maven启动脚本或MAVEN_OPTS里的。在你配置的MAVEN_OPTS环境变量中加入-Dmaven.wagon.http.retryHandler.count3 -Dmaven.wagon.http.connectionTimeout12000这类参数能让下载更耐折腾。不过说实话我现在大多数时间在IDEA里操作IDEA自带的Maven插件对下载失败的提示和处理已经很友好了所以在命令行踩到这类问题的概率不高。第二件是把.m2目录里的repository按需清理。装了一堆实验项目后本地仓库会有大量temp文件.part文件和失败的下载残留。手动清理比较麻烦我一般会在确定网络正常的情况下执行mvn dependency:purge-local-repository它会清理本地仓库里没有正确安装或损坏的依赖。这个命令不能常用因为会牵连并移除大量其他项目需要的依赖推荐只在明确要清理某个特定依赖时才配合-Dinclude参数使用。4. IDEA集成Maven全局配置、新建项目与导入项目一次理清如果你只是用命令行操作Maven那对绝大部分Java开发者来说还不够——大家日常开发几乎都在IntelliJ IDEA里完成所以让IDEA和Maven配合顺畅才是真正提升日常效率的关键。4.1 为什么IDEA自带的Maven不够用IDEA默认自带了一个捆绑版的Maven位置在IDEA安装目录的plugins\maven\lib\maven3下。这个自带Maven的好处是开箱即用——你新建Maven项目时它就能直接跑。但它有几个问题版本通常是IDEA发布时固定的可能不是最新版而且它默认使用独立的settings配置并不会自动读取你手动修改的那个settings.xml比如你配置的阿里云镜像和本地仓库路径。也就是说如果你完全依赖IDEA自带的Maven你在命令行里做的那些配置优化IDEA里一个都用不上。所以我一直强调在IDEA里显式指定你自己的Maven安装目录和配置文件一次配置终身受用。4.2 全局Maven设置的正确操作打开IDEA依次进入File - SettingsWindows/Linux或IntelliJ IDEA - PreferencesmacOS在左侧搜索框输入Maven然后找到Build, Execution, Deployment - Build Tools - Maven。这里有三个关键选项Maven home path选择你本机Maven的解压目录比如D:\dev\apache-maven-3.9.9也就是包含bin、conf、lib的目录而不是直接选到bin。User settings file点击右侧的Override复选框然后选择你的settings.xml路径。这里要注意如果IDEA提示file not exist之类的错误先确认你选对的是配置文件而不是目录。Local repository正常情况下只要你正确指定了User settings file这个字段会自动显示为你settings.xml里配置的localRepository路径。如果没有自动关联也可以手动选择到对应的本地仓库目录。这三项设置好之后再往下看有个Runner选项卡同页面少数版本在Build Tools - Maven - Runner中我建议在VM Options和Properties里做两件事——VM Options填入-Dfile.encodingUTF-8Environment variables里确保不缺少JAVA_HOME通常IDEA会自动继承系统环境变量但如果你是在IDEA里遇到编码问题这种显式声明的方式会更为可控。设置完之后点击Apply和OK保存。注意IDEA顶级版的Settings针对不同项目会有全局和项目两种作用域。如果你希望以后新建的所有项目都自动继承这套配置就要在File - New Projects Settings - Settings for New Projects里再做一次同样的设置。我在刚用IDEA时也经常忘记这一步后来养成了习惯装好IDEA后第一件事就是同时在Settings for New Projects和当前项目的Settings里配置Maven确保新旧项目都不掉队。4.3 新建Maven项目和导入已有Maven项目的实操新建项目时在左侧选择Maven然后选择一个合适的JDKIDEA会自动检测到系统的JDK比如JDK 17。如果你是一个Web项目通常还会勾选Create from archetype中选择maven-archetype-webapp如果是普通Java应用直接什么都不选让IDEA生成最简洁的pom.xml结构就行。IDEA会自动调用你刚才配置的Maven来初始化项目的依赖索引。导入已有Maven项目时操作就更简单了File - Open直接选择项目根目录下的pom.xmlIDEA会识别这是一个Maven项目并加载依赖。如果IDE没有自动识别可以右键pom.xml文件选择Add as Maven Project。导入后IDEA会在右侧的Maven工具面板中展示项目的所有生命周期命令和依赖列表你可以直接双击package、clean等命令来执行不用再去敲命令行。这里有一个易错点很多项目在导入时IDEA右下角会弹出一个提示Maven projects need to be imported或者Non-managed pom.xml file found。如果你点了忽略或者关闭弹窗可能导致依赖索引没有正确建立。我的习惯是看到这类提示就点击Enable Auto-Import或Import Changes让IDEA自动监视pom.xml的变更以后你改依赖时就能自动同步。4.4 用插件和内置功能让Maven操作更顺手IDEA里有一些常用插件能让Maven相关操作变得更顺手。第一个是Maven Helper插件它最实用的功能是依赖冲突分析。第二个是Lombok插件配合Lombok依赖可以大幅减少样板代码。第三个是Alibaba Java Coding Guidelines插件不过它跟Maven配置无关但通常和Maven项目配合使用帮你检查代码规范。IDEA的Maven工具面板有几个高频操作我每次做项目几乎必点双击package或install的时候如果项目有测试环节想跳过测试可以点击面板上的Toggle Skip Tests按钮一个蓝色的圆形箭头带一个test字样激活测试跳过模式这样IDEA执行的命令就带上了-DskipTests参数省去等测试编译和运行的不少时间。同时Lifecycle下的clean和install是部署前的黄金组合先clean清理掉之前编译的所有class文件和jar包再install把当前项目安装到本地仓库供其他项目以依赖方式引用。还有一个小但实用的功能IDEA的Maven面板里每个依赖项右键都有Download Sources和Download Javadoc选项。我建议至少给经常阅读源码的核心依赖比如Spring、MyBatis下载Sources这样按Ctrl点击类名时直接跳转到源码而不是反编译的字节码调试和理解代码会舒服很多。设置里这些通常默认不勾选但某些版本IDEA能在每次Maven刷新时自动下载sources如果你发现没有生效可以手动右键一次。5. 高频踩坑实录与完整排查链路这一节是今天真正的干货部分。我在Windows上搭Maven环境这些年被各种奇奇怪怪的问题卡过也帮不少同事排查过环境问题。下面按踩坑频率从高到低把经典的几个问题、排查链路和解决方案完整写出来。5.1 mvn 不是内部或外部命令环境变量排查三板斧这个问题几乎每个新手都遇到过但你只要掌握一个系统的排查链路后面就不再会慌。第一步检查系统变量MAVEN_HOME是否已经创建值是否指向Maven实际解压目录。在命令行执行echo %MAVEN_HOME%如果输出的是%MAVEN_HOME%原样说明这个变量根本没配上如果输出的是字符串MAVEN_HOME而不是具体路径说明变量名写错了或没保存成功。第二步检查Path变量里是否包含%MAVEN_HOME%\bin。执行echo %PATH%看看输出中有没有D:\dev\apache-maven-3.9.9\bin这串内容。注意如果你手误按引号把Path原值覆盖了会导致系统一堆命令都失效那问题就更麻烦了。因此编辑Path时务必选择编辑文本并保留已有变量或者使用编辑环境变量界面一行行追加。第三步如果环境变量都对但还是报不是内部或外部命令先确认你执行的命令行窗口是不是配置环境变量之前就打开的。Windows的命令行环境变量是在进程启动时读取的旧窗口不会自动更新。关掉所有cmd窗口重新开一个再执行mvn -v。如果你做完上述三步还是不行再检查一个冷门原因Maven安装目录的权限。在某些公司电脑上管理员策略会限制普通用户对Program Files等目录的读写权限导致mvn.cmd无法正常执行。解决办法是不要把Maven解压到这类系统管控目录放到D盘个人目录下。这个坑在Windows Server和公司域环境里尤其常见。5.2 依赖下载超时、卡住不动、一直Downloading这个问题几乎每个人都遇到过尤其是在没有配置阿里云镜像时。我的排查思路是这样。第一步看你的settings.xml里有没有配置镜像源。执行mvn help:effective-settings看输出的mirror部分。如果显示为空说明你IDEA或命令行使用的根本不是你以为的那个配置文件。这一点特别重要IDEA里可能覆盖了User settings file路径你改的是D:\dev\apache-maven-3.9.9\conf\settings.xml但IDEA指向的却是C:\Users\xxx\.m2\settings.xml。我见过太多同事改错文件排查了半天最后发现改的路径和实际生效的路径根本不一致。第二步确认本地仓库路径没有指向一个网络驱动器。有个别公司会把用户目录映射到网络盘Maven下载依赖时要经过网络盘速度极其感人。这种情况下一定要把localRepository改成纯本地磁盘路径。第三步检查防火墙或代理设置。如果你的网络环境需要代理才能访问外网Maven默认不会自动使用系统代理。你需要在settings.xml里的proxies标签中加入代理配置proxy iddefault/id activetrue/active protocolhttp/protocol host代理服务器地址/host port代理端口/port username用户名可选/username password密码可选/password /proxy如果公司内网有一台Nexus私服那更建议直接在镜像配置里指向内网Nexus或者用repositories和pluginRepositories明确指定内网仓库地址这样不仅速度快安全性也更有保障。5.3 IDEA报Unable to import Maven project或依赖标红IDEA导入Maven项目失败最常见的原因就是你之前在第4章提到的Maven配置不统一。如果你给IDEA指定的Maven home path是自带的那个捆绑Maven同时User settings file又指向了你自己改过的配置文件实际上这两者是可以共存的但有些细小的错误会导致IDEA在刷新项目时直接报错。我的排查顺序是首先看IDEA的Settings - Build Tools - Maven里Maven home path是否指向有效目录。然后点击Maven设置页面下的Maven - Importing在Import Maven projects automatically前打勾有时这能触发IDEA重新加载。其次如果你有多个版本的Maven在机器上确保IDEA和命令行用的是同一个版本比较省心否则本地仓库同一个坐标的jar包可能被不同版本Maven以不同结构缓存虽然通常不影响但偶尔会出现重构失败。如果项目依赖全部标红先不要怀疑Maven有问题而是看看右下角的Event Log和Maven面板的刷新日志。如果是Could not transfer artifact这类提示一般就是下载失败了按照5.2的方式解决网络问题即可如果是Invalid Maven home directory说明IDEA里Maven home path指错了重新定位到解压目录即可。还有一种情况比较隐蔽项目本身用的某个依赖来自私有仓库而你的settings.xml里虽然配置了阿里云镜像但mirrorOf写的是*把所有仓库请求都强制转发到阿里云导致私有仓库的依赖拉不下来。解决办法是把mirrorOf改成central只镜像中央仓库私有仓库请求仍然走原仓库地址。5.4 多模块项目踩坑父POM和依赖管理多模块项目比如Spring Cloud微服务架构遇到的Maven问题比单模块项目高一个复杂度。常见的问题是用IDEA导入多模块项目后子模块之间互相依赖的类引用不到或者子模块版本对不上。这里的核心知识点是父pom.xml里用dependencyManagement管理所有子模块的依赖版本但父POM本身并不直接引入这些依赖子模块里只需要声明groupId和artifactId不需要重复写version。这样版本就能统一管理。很多新手会在子模块里继续写死版本号导致父母和子模块版本不一致编译报错或者运行时行为不一致。排查多模块问题时先执行mvn clean install -DskipTests把整个工程在本地仓库装一遍这样依赖关系就基于本地仓库建立了。然后在IDEA的Maven面板里点刷新按钮一个圆形箭头图标让IDEA重新读取依赖关系。如果还是标红右键具体模块选择Reload或Synchronize。另外多模块项目在Windows下如果路径特别长比如模块层级很深、目录名很长可能会报路径过长无法创建文件的错误。这是因为Windows默认的MAX_PATH限制是260个字符。解决办法是在注册表HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem下把LongPathsEnabled的值改为1并确保开发机启用了长路径支持。或者更简单粗暴把整个项目路径放到短目录下比如D:\proj\能快速规避问题。5.5 编码问题控制台乱码与编译警告最后聊一个和Windows强相关的细节——编码问题。默认情况下Windows的cmd窗口代码页是GBKCP936而Maven构建时的源码如果是UTF-8会在编译时给出不可映射字符的警告甚至在某些严格配置下直接编译失败。解决方案有两个。第一个方案是在pom.xml里显式声明编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding maven.compiler.encodingUTF-8/maven.compiler.encoding /properties第二个方案是在命令行执行编译时加参数mvn clean package -Dfile.encodingUTF-8。如果用的是IDEA频繁执行Maven命令直接在IDEA的Maven Runner配置里把VM Options设为-Dfile.encodingUTF-8这样IDEA调用的所有Maven命令都会带上这个参数源码和编译输出都统一为UTF-8。乱码问题还经常出现在IDEA的Build控制台输出上。如果你发现Maven编译日志里的中文全部成了乱码可以先在Help - Edit Custom VM Options里加上-Dfile.encodingUTF-8重启IDEA后再看是否恢复。这属于IDEA自身的JVM编码和Maven环境变量里的MAVEN_OPTS是两回事别混在一起。6. 我个人用的Maven配置模板可直接抄最后分享一份我目前Windows开发机上正在用的settings.xml核心片段。它是我多次踩坑后收敛的结果在IDEA和命令行之间行为完全一致。如果你不想从零开始一点一点对可以直接将以下内容覆盖conf/settings.xml中对应部分。?xml version1.0 encodingUTF-8? settings xmlnshttp://maven.apache.org/SETTINGS/1.2.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd localRepositoryD:\dev\maven-repository/localRepository mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors profiles profile idjdk-17/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target maven.compiler.compilerVersion17/maven.compiler.compilerVersion project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties /profile /profiles /settings注意我把mirrorOf写成了central而不是*这是权衡之后的结果如果你的项目只用中央仓库的依赖两者没有区别如果以后要接入公司私有仓库central不会误伤私有仓库请求可以减少一类非常隐蔽的问题。IDEA侧我建议确认三件事Maven home path指向本机安装的Maven目录而非内置MavenUser settings file勾选Override后指向上述settings.xmlLocal repository自动关联为D:\dev\maven-repository。这三处一致后你的命令行和IDEA就完全同步了再也不会出现IDEA里能跑、命令行不行或者反过来。最后再多说一句经验之谈如果你用的是公司标准化的开发环境比如装了统一的JDK目录、统一了Maven版本一定先问清楚公司私服的地址和账号。配置私服的优先级永远高于公共阿里云镜像——私有包拉不下来镜像再快也白搭。把这些搞明白了Windows下Maven这套东西基本就再也难不住你了。