简介Apache Maven 3.6.2 的二进制压缩包面向 Java 开发者、项目构建维护者及需要统一依赖与构建流程的团队用于在本地快速搭建 Maven 环境简化编译、测试、打包、部署与依赖管理。压缩包共 68 个文件约 8.77MB以 42 个 jar 核心库和插件依赖为主辅以许可证、通知、跨平台本地库、启动脚本及 XML、conf 配置文件覆盖 Windows 与类 Unix 环境下的运行需要。已有 323 人学习下载说明其在 Java 构建工具入门与环境配置场景中具有一定参考价值。包内保留完整的 Maven 发行版目录结构便于读者理解核心目录分工并借助标准 POM、插件机制和全局配置完成依赖解析、构建生命周期管理及多环境适配适合作为学习 Maven 3.6.2 与排查构建问题的实用工具包。1. 从一次依赖拉不下来说起Maven 3.6.2 的安装窗口上周帮一个刚转到 Java 组的同事看环境项目 clone 下来mvn clean package一跑控制台刷了两屏红色最后停在Could not resolve dependencies。他以为是代码问题折腾了一下午其实是机器上压根没装 MavenIDE 自带的那个内嵌版本又被代理设置搅乱了。这种场景太常见了项目能 cloneJDK 也装了就差一个能把pom.xml翻译成 jar 包的构建工具。Apache Maven 3.6.2 是 3.6.x 分支里被大量老项目钉死的一个版本很多公司内部的settings.xml、私服地址、插件版本都是照它调的。装错版本或者装完不配环境变量轻则命令行找不到mvn重则编译时插件报Unsupported class file major version一天就没了。这篇笔记把下载、解压、环境变量、settings.xml、验证和翻车自救按顺序走一遍适合第一次在 Windows 或 Linux 上搭 Java 构建环境的人也适合要把老项目迁移到新机器上的熟手对照。2. 装前把环境钉死JDK 版本与目录规划Maven 本身是个 Java 程序它不编译代码只调度插件所以第一件事不是下载 Maven而是确认 JDK。Maven 3.6.2 要求 JDK 7 以上才能启动但实际项目里编译目标常常是 8 或 11这两件事必须分开看启动 Maven 用哪个 JDK编译项目用哪个 JDK配错了就是玄学报错的源头。2.1 JDK 版本对照与选择建议我一般按项目pom.xml里的maven.compiler.source反推。如果项目写着 1.8那就老老实实装 JDK 8如果写着 11JDK 11 起步。Maven 3.6.2 在 JDK 17 上跑会有插件兼容问题尤其是老版maven-compiler-plugin容易在编译阶段抛IllegalAccessError。下面的对照表是我自己踩过之后记下来的项目编译目标建议 JDKMaven 3.6.2 表现备注1.6 / 1.7JDK 8正常老项目插件要跟着降级1.8JDK 8最稳生产环境主流组合11JDK 11正常注意maven-compiler-plugin升到 3.817JDK 17插件易翻车建议换 Maven 3.8确认 JDK 的命令很简单但要看清楚输出里的版本号和厂商# Windows 和 Linux 通用先确认 java 在 PATH 里 java -version # 输出类似 openjdk version 1.8.0_392记下主版本 javac -versionjava -version看的是运行时javac -version看的是编译器两个都要有。只有 JRE 没有 JDK 的机器上javac会提示找不到命令这种机器装完 Maven 能启动但一编译就报No compiler is provided in this environment。2.2 安装目录规划别把 Maven 放进 Program FilesWindows 上很多人习惯把解压出来的目录扔进C:\Program Files\结果路径里有空格某些老插件拼命令行时直接断掉。我的习惯是统一放到一个无空格、无中文的短路径下# Linux / macOS 常用位置 /opt/apache-maven-3.6.2 # Windows 常用位置 D:\dev\apache-maven-3.6.2目录规划还要考虑本地仓库。Maven 默认把依赖下到~/.m2/repositoryWindows 上是C:\Users\用户名\.m2\repository。如果 C 盘紧张或者公司要求依赖统一放数据盘就在settings.xml里改localRepository。这一步在装之前想清楚比装完之后搬仓库省事得多搬仓库最容易遇到的是残留的_remote.repositories文件导致依赖校验失败。2.3 下载与解压校验压缩包完整性拿到apache-maven-3.6.2.zip之后先别急着解压。压缩包传输损坏是真实存在的解压到一半报CRC error的情况我见过不止一次。Windows 上可以用 PowerShell 算一下哈希和发布页给的 SHA-512 对一下# Windows PowerShell计算 SHA512 Get-FileHash .\apache-maven-3.6.2.zip -Algorithm SHA512 # Linux / macOS shasum -a 512 apache-maven-3.6.2.zip哈希对得上再解压。解压后目录结构应该是bin/、boot/、conf/、lib/四个核心目录bin下有mvnLinux/macOS 脚本和mvn.cmdWindows 批处理conf下有全局的settings.xml。如果解压出来多了一层同名目录比如apache-maven-3.6.2/apache-maven-3.6.2/bin说明解压工具自动建了文件夹配环境变量时路径就会指错一层这是最常见的第一坑。3. 配环境变量MAVEN_HOME 与 PATH 的三个易错点Maven 装完能不能在任意目录下敲mvn全看环境变量。这一章的动作在 Windows 和 Linux 上不一样但逻辑一致先告诉系统 Maven 装在哪再把它的bin塞进 PATH。3.1 Windows 下的 MAVEN_HOME 与 PATH 配置Windows 走图形界面或者setx命令都行。我倾向用setx因为可复现也方便写进部署脚本。注意setx有长度限制PATH 太长会被截断所以改 PATH 之前先备份一下原值。# 设置 MAVEN_HOME路径换成你自己的解压位置 setx MAVEN_HOME D:\dev\apache-maven-3.6.2 # 把 bin 追加到 PATH%MAVEN_HOME%\bin 是固定写法 setx PATH %PATH%;%MAVEN_HOME%\bin第一条命令设置MAVEN_HOME指向解压后的根目录不是bin目录。第二条把%MAVEN_HOME%\bin追加到 PATH 末尾。这里有个细节setx写入的是用户级变量新开的终端才生效已经打开的 cmd 或 PowerShell 窗口读不到。配完必须关掉所有终端重开这一点坑过太多人敲mvn -v提示不是内部命令八成就是没重开窗口。另一个易错点是 PATH 里已经有旧版 Maven 的bin。如果之前装过 3.5.xPATH 里残留一条路径系统会优先命中旧的那个mvn -v显示的版本和你以为的不一样。排查方法是where mvnWindows或which -a mvnLinux把所有命中的路径列出来按顺序看哪个在前。3.2 Linux 与 macOS 下的 profile 写法Linux 上改~/.bashrc还是/etc/profile取决于影响范围。只给自己用就改~/.bashrc或~/.zshrc给整台机器所有用户用就改/etc/profile.d/下新建一个maven.sh。# 写入 ~/.bashrczsh 用户换成 ~/.zshrc export MAVEN_HOME/opt/apache-maven-3.6.2 export PATH$MAVEN_HOME/bin:$PATHexport让变量对子进程可见这是 Maven 启动脚本读取MAVEN_HOME的前提。PATH 拼接时把$MAVEN_HOME/bin放在前面保证优先命中新装的版本。改完执行source ~/.bashrc让当前会话生效注意source只影响当前 shell其他已开的终端还是要重开。macOS 从 Catalina 起默认 shell 是 zsh改错文件是高频翻车点改了.bashrc却在 zsh 里敲命令怎么都不生效。判断方法很简单echo $SHELL看输出是/bin/zsh还是/bin/bash对着改就行。3.3 用 mvn -v 做第一次冒烟验证环境变量配完第一件事是mvn -v别急着跑构建。这个命令会打印 Maven 版本、安装路径、JDK 版本和系统信息一次性验证三件事PATH 找到没有、MAVEN_HOME解析对不对、Maven 能不能启动 JVM。mvn -v # 期望输出结构 # Apache Maven 3.6.2 (...) # Maven home: D:\dev\apache-maven-3.6.2\bin\.. # Java version: 1.8.0_392, vendor: ... # Java home: ... # OS name: windows 10, ...重点看Maven home这一行。如果显示的是...\bin\..说明MAVEN_HOME指对了根目录如果显示成...\bin\bin或者路径里带着两层目录名就是路径多指或少指了一层。Java home也要看它决定了 Maven 启动用哪个 JDK和项目编译用的 JDK 不一定是同一个后面配toolchains或者改JAVA_HOME时还会用到这个信息。4. 配 settings.xml本地仓库、镜像与代理的取舍Maven 真正的配置重心不在安装目录而在用户级的settings.xml。安装目录conf/settings.xml是全局默认改它影响所有用户升级时容易被覆盖用户目录~/.m2/settings.xml是个人配置优先级更高我一般只改这一份。4.1 用 localRepository 把仓库挪出系统盘默认仓库在~/.m2/repository依赖多了能占十几个 G。要挪位置就在settings.xml里加一行settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 !-- 本地仓库路径Windows 用正斜杠或双反斜杠 -- localRepositoryD:/maven-repo/localRepository /settingslocalRepository写绝对路径Windows 下建议用正斜杠D:/maven-repo避免反斜杠在 XML 里被当转义。这个目录第一次构建时会自动创建不需要手动建。已经有一份旧仓库要迁移的话整个目录拷过去就行但要注意拷完之后删掉里面的_remote.repositories文件否则 Maven 会拿旧仓库的来源记录去校验私有依赖容易报was cached in the local repository, resolution will not be reattempted。4.2 镜像配置mirrorOf 写错就是全盘失效国内拉中央仓库依赖慢是常态配镜像几乎是必做项。镜像写在mirrors里核心参数是mirrorOf它决定了哪些仓库请求被这个镜像接管。mirrors mirror !-- 镜像唯一标识随便起但要唯一 -- idinternal-mirror/id !-- 镜像地址换成公司私服或可用的公共镜像 -- urlhttps://repo.example.com/maven-public//url !-- 关键* 表示接管所有仓库请求 -- mirrorOfcentral/mirrorOf /mirror /mirrorsmirrorOf的取值有讲究写central只接管中央仓库写*接管所有包括项目pom.xml里自定义的仓库写external:*接管所有外部仓库但保留 localhost 和 file 协议。全写*最省事但如果公司项目依赖了某个内部仓库*会把内部请求也劫持到公共镜像结果就是私服包拉不到报 404。正确做法是用external:*,!internal-repo这种排除语法或者干脆只写central。还有一个坑id不要和pom.xml里repository的id撞名。Maven 做认证时会按id匹配settings.xml里的server配置撞名了会用错账号密码报 401。4.3 代理与超时参数什么时候该配什么时候别碰如果机器在公司内网出网必须走 HTTP 代理那就在settings.xml里配proxiesproxies proxy idcompany-proxy/id activetrue/active protocolhttp/protocol hostproxy.example.com/host port8080/port !-- nonProxyHosts 里的地址不走代理用 | 分隔 -- nonProxyHostslocalhost|127.0.0.1|*.example.com/nonProxyHosts /proxy /proxiesactive为true才启用nonProxyHosts用竖线分隔支持通配符把内网私服和本机地址排除掉不然拉私服包也会绕代理速度慢还容易超时。如果机器能直连外网这一段整个删掉配了反而可能因为代理不可达导致所有依赖下载失败。超时相关的是server里的连接配置以及环境变量MAVEN_OPTS。拉大依赖卡住时我一般临时加# 加大堆内存和连接超时单位毫秒 export MAVEN_OPTS-Xmx1024m -Dmaven.wagon.http.connectionTimeout60000-Xmx控制 Maven 进程堆大小大项目构建时OutOfMemoryError多半靠它救maven.wagon.http.connectionTimeout是 wagon 传输层的连接超时网络抖动大的环境调大一点能减少Read timed out。这两个参数不要长期写死在全局配置里按需临时加更稳妥。5. 避坑排查五条装完才发现的翻车记录安装阶段的问题有个特点报错信息往往指向项目实际根因在环境。下面五条是我在不同机器上真实遇到过的按「现象 → 原因 → 解决」记下来。5.1 mvn 不是内部或外部命令现象配完环境变量新开终端敲mvn -vWindows 报mvn 不是内部或外部命令Linux 报mvn: command not found。原因有三个可能PATH 里拼的是%MAVEN_HOME%\bin但MAVEN_HOME没生效MAVEN_HOME指到了bin目录导致实际路径变成bin/bin改的是用户变量但当前终端是以管理员或其他用户身份开的。解决先用echo %MAVEN_HOME%Windows或echo $MAVEN_HOMELinux确认真实值再dir %MAVEN_HOME%\bin\mvn.cmd确认文件存在。Linux 下还要确认bin/mvn有执行权限chmod x bin/mvn补一下。最后关掉所有终端重开别在旧窗口里反复试。5.2 构建卡在 Downloading 不动现象mvn clean install跑到一半停住控制台一直显示Downloading from central: https://...几分钟后抛Read timed out。原因镜像地址不可达或者mirrorOf写成了*导致所有请求都走一个慢镜像也可能是代理配了但代理本身不通。解决先ping或curl -I镜像地址确认连通性再看settings.xml里mirrorOf是不是过宽临时用mvn -U clean install强制更新快照如果确认是代理问题把proxies里active改成false试一次能过就说明代理配置有误。5.3 私服依赖 401 或 403现象公共依赖能拉公司私服的包报401 Unauthorized或403 Forbidden。原因settings.xml的servers里没有对应id的账号密码或者id和pom.xml里repository的id对不上Maven 找不到凭据。解决在servers里加一条id必须和仓库id完全一致大小写敏感servers server !-- 这个 id 必须和 pom 里 repository 的 id 一模一样 -- idinternal-repo/id usernamedeploy-user/username password******/password /server /servers密码不要明文长期放着能用环境变量或外部加密就优先用。改完清一下本地仓库里对应目录下的*.lastUpdated文件否则 Maven 会认为刚失败过短时间内不再重试。5.4 编译报 Unsupported class file major version现象mvn compile报Unsupported class file major version 61或类似数字或者插件加载时抛UnsupportedClassVersionError。原因Maven 启动用的 JDK 版本低于插件编译时用的版本。数字 61 对应 Java 1752 对应 Java 8。Maven 3.6.2 跑在老 JDK 8 上加载了用 17 编译的插件就会报这个。解决确认mvn -v输出的Java version和项目要求对齐。需要同时保留多套 JDK 的配toolchains.xml或者在命令行临时指定JAVA_HOME# 临时切换本次构建用的 JDK export JAVA_HOME/usr/lib/jvm/java-11-openjdk mvn -vWindows 下同理set JAVA_HOMED:\dev\jdk11注意只影响当前窗口。5.5 依赖明明下载了却提示找不到现象本地仓库目录里能看到 jar 包构建仍报Could not find artifact。原因最常见的是仓库迁移后残留_remote.repositories其次是 jar 只下了一半目录里有.part或.lastUpdated文件还有一种是把localRepository改到了新路径但旧仓库没拷全。解决先看报错里给的路径进目录确认 jar 大小是否正常一般几 KB 的都是坏包。删掉同目录下的*.lastUpdated和_remote.repositories再mvn -U重跑。整仓出问题时最直接的办法是删掉对应groupId目录重下别舍不得缓存坏了越修越乱。6. 装完怎么验证用一个小工程跑通全链路环境装没装好mvn -v只能证明 Maven 能启动证明不了依赖能拉、插件能跑、编译能过。我的习惯是拿一个最小工程把这四件事一次性验证掉比在真实项目上排错省时间得多。6.1 三步验证法第一步建一个空目录手写一个最小pom.xml只依赖一个体积小、来源稳定的公共库不要用公司私服包先把公共链路跑通project xmlnshttp://maven.apache.org/POM/4.0.0 modelVersion4.0.0/modelVersion !-- 坐标随便起不参与发布 -- groupIdlocal.smoke/groupId artifactIdsmoke-test/artifactId version1.0.0/version properties !-- 和本机 JDK 对齐别写太高 -- maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdjunit/groupId artifactIdjunit/artifactId version4.12/version scopetest/scope /dependency /dependencies /project第二步在src/main/java下放一个只有main方法的类跑mvn -U clean package。这一步验证的是镜像通不通、依赖能不能下、编译器插件能不能加载、打包插件能不能产出 jar。第三步跑mvn dependency:tree看依赖树能不能完整打印。这一步验证的是依赖解析和冲突调解如果前面都能过但这步报错问题基本出在某个传递依赖上报错信息会直接指出是哪个坐标。6.2 验证结果怎么读三步都过了基本可以确认环境可用。但有几个输出细节值得多看一眼我列成表验证动作关键输出异常含义mvn -vMaven home路径多一层或少一层目录mvn -vJava version与项目编译目标不符mvn packageBUILD SUCCESS出现 WARNING 要看是否插件版本过旧mvn dependency:tree完整依赖层级出现omitted for conflict属正常调解mvn package耗时首次明显长于后续首次在下载后续走本地缓存BUILD SUCCESS后面如果跟着一串WARNING比如The requested profile xxx could not be activated说明settings.xml里配了activeProfiles但 profile 定义不在这种不影响构建但会埋雷顺手清掉。还有一个小技巧验证通过之后把这份最小工程的pom.xml和你的settings.xml一起留个备份换机器或者重装时直接拷过去跑一遍比重新回忆配了哪些参数快得多。我第一次配 Maven 时没留备份后来换笔记本光回忆mirrorOf当时写的是什么就花了半小时从那以后每次装完环境我都会把这个冒烟工程和配置文件一起归档新机器上先跑它再碰真实项目。希望这套流程能帮你少走一遍我走过的弯路。本文还有配套的精品资源点击获取