简介：Apache Maven 3.6.2 官方发行压缩包，面向 Java 开发者、构建工程师及需要统一项目构建流程的团队，用于解决依赖管理繁琐、构建过程不一致等问题，适合从入门配置到日常项目构建的各类场景。包内共 68 个文件，以 42 个 jar 核心库与插件依赖为主，辅以 so、dll、jnilib 等本地库文件、cmd 与 mvn 启动脚本、xml 配置文件及 license、notice 等许可说明，压缩包约 8.77MB，体积轻量、开箱即用。目录涵盖 bin 可执行脚本、boot 引导组件、conf 全局配置与 lib 运行库，settings.xml 可集中管理本地仓库、远程仓库与代理设置，便于快速搭建标准化构建环境。已有 323 人学习下载，读者可据此完成 Maven 本地安装、依赖解析与构建任务配置，并借助插件机制扩展打包、测试、部署等能力，减少重复配置成本。

1. 从一台干净机器说起：apache-maven-3.6.2.zip 到底装的是什么

上周帮同事配一台新机器，JDK 装好了，java -version也正常，结果一敲mvn -v直接报「不是内部或外部命令」。他以为 Maven 是个安装包，双击下一步就行，翻遍下载目录也没找到 exe。这就是最典型的翻车现场：apache-maven-3.6.2.zip 是免安装的二进制压缩包，解压即用，但「解压即用」不等于「解压就能跑」，中间还隔着环境变量、本地仓库、JDK 版本匹配这几道坎。这篇笔记就按我实际装机的顺序，把 3.6.2 这个版本从解压到跑通一条龙写清楚，适合刚接手 Java 项目、需要自己搭构建环境的人照着走，也适合熟手对照看看参数取舍。

2. 装前把环境列清：JDK 版本与目录规划

2.1 先确认 JDK，再谈 Maven 版本

Maven 本身不编译代码，它调用的是 JDK 里的javac，所以 JDK 没配对，Maven 装得再对也白搭。apache-maven-3.6.2 这个版本对 JDK 的要求是 7 及以上，但实际项目里我一般不会低于 JDK 8。原因很直接：3.6.x 系列配套的 maven-compiler-plugin 默认 source/target 是 1.6，如果你项目里写的是 JDK 8 的 lambda，编译阶段就会报「lambda expressions are not supported in -source 1.6」，这个坑后面避坑章还会细说。

装之前先跑两条命令确认现状：

# 确认 JDK 版本，输出里要有 1.8 或更高 java -version # 确认 javac 也在，Maven 编译阶段依赖它 javac -version

逻辑说明：java -version看的是运行环境，javac -version看的是编译工具链，两者版本号必须一致。常见情况是机器上装了多个 JDK，java指向 8，javac却指向 11，这种错位在 Maven 编译时表现得很隐蔽——报错信息指向源码语法，实际是工具链不一致。我一般会顺手看一眼JAVA_HOME：

# Linux / macOS echo $JAVA_HOME # Windows CMD echo %JAVA_HOME%

JAVA_HOME必须指向 JDK 根目录，不是jre子目录，也不是bin目录。这一点在 Windows 上尤其容易写错，因为 JDK 安装器默认会把java.exe也塞进C:\Windows\System32，导致java -version能跑但JAVA_HOME是空的，Maven 启动时就会去找默认 JRE，行为不可控。

2.2 目录规划：别把 Maven 解压到带空格的路径

apache-maven-3.6.2.zip 解压后是一个apache-maven-3.6.2目录，里面bin、conf、lib三层结构。我见过最常见的翻车是把整个目录丢进C:\Program Files\或者「我的文档」下面，路径里带空格，然后mvn命令时好时坏。原因是 Maven 的启动脚本mvn.cmd里对路径做了引号处理，但部分插件在拼接 classpath 时对空格处理不干净，表现就是某些 goal 能跑、某些 goal 报「Could not find or load main class」。

我的习惯是统一放一个无空格、无中文的短路径：

解压命令按平台来：

# Linux / macOS，解压到 /opt 或 ~/dev unzip apache-maven-3.6.2.zip -d /opt/ # 解压后确认目录结构，应该能看到 bin/conf/lib ls /opt/apache-maven-3.6.2

Windows 上直接右键「全部解压缩」即可，但要注意解压工具有时会多套一层目录，变成apache-maven-3.6.2\apache-maven-3.6.2\bin，配环境变量时就会指错。解压完先cd进去看一眼，确认bin目录就在第一层。

2.3 版本选择的取舍：为什么是 3.6.2 而不是更新版本

3.6.2 是 3.6.x 系列里比较稳的一个点，发布于 2019 年，配套的 Maven 核心和插件生态成熟。选它通常有两个现实原因：一是老项目pom.xml里锁了插件版本，新 Maven 对某些老插件的默认行为有变化；二是团队统一版本，避免「我这能跑你那不能跑」。如果你是从零起的新项目，其实可以上 3.8.x 或 3.9.x，但 3.6.2 在兼容老项目这件事上踩坑最少。这里不做版本推荐，只提醒一句：Maven 版本和项目里的maven-compiler-plugin、maven-surefire-plugin版本是联动的，换 Maven 大版本前先看pom.xml里锁了什么。

3. 配环境变量：三个路径写错一个就白装

3.1 设置 MAVEN_HOME 与 PATH

环境变量是 Maven 免安装包能不能跑起来的关键。核心就两个：MAVEN_HOME指向解压目录，PATH里追加%MAVEN_HOME%\bin（Windows）或$MAVEN_HOME/bin（Linux/macOS）。先看 Linux/macOS 的写法：

# 编辑当前用户的 shell 配置，bash 用 .bashrc，zsh 用 .zshrc vim ~/.bashrc # 在文件末尾追加，注意路径换成你实际解压的位置 export MAVEN_HOME=/opt/apache-maven-3.6.2 export PATH=$MAVEN_HOME/bin:$PATH

逻辑说明：MAVEN_HOME是给 Maven 自己和部分插件读的，PATH是给 shell 找mvn命令用的。$PATH放在后面是让 Maven 的 bin 优先于系统里可能存在的旧版本。改完必须source ~/.bashrc或者重开终端，否则当前会话读不到新变量。验证方式：

# 确认变量生效 echo $MAVEN_HOME # 确认 mvn 能找到 which mvn

Windows 上的操作路径是「此电脑 → 属性 → 高级系统设置 → 环境变量」，在系统变量里新建MAVEN_HOME，值是D:\dev\apache-maven-3.6.2，然后在Path里新增一条%MAVEN_HOME%\bin。这里有个血泪经验：Windows 的Path编辑界面分「用户变量」和「系统变量」，如果你只在用户变量里加了，换一个用户登录就找不到mvn；如果机器是多人共用或者要跑服务，加到系统变量里更稳。

3.2 验证 mvn -v 输出的三行信息

配完变量，第一件事不是急着跑项目，而是mvn -v。正常输出长这样：

mvn -v # 预期输出（版本号和路径以实际为准） # Apache Maven 3.6.2 (40f52333136460af0dc0d7232c0dc0bcf0d9e117) # Maven home: /opt/apache-maven-3.6.2 # Java version: 1.8.0_301, vendor: Oracle Corporation # Java home: /usr/lib/jvm/java-8-openjdk-amd64/jre # Default locale: zh_CN, platform encoding: UTF-8 # OS name: "linux", version: "5.4.0", arch: "amd64", family: "unix"

这三行信息要逐行核对：第一行确认 Maven 版本是 3.6.2，不是系统里残留的旧版本；第二行Maven home必须和你解压的路径一致，不一致说明MAVEN_HOME指错了或者 PATH 里有别的 mvn 抢先；第三行Java version和Java home必须指向你预期的 JDK，如果这里显示的是 JRE 路径或者版本不对，说明JAVA_HOME有问题，Maven 回退到了默认 JRE。

提示：mvn -v里Java home显示到jre子目录是正常的，Maven 读的是运行时；但JAVA_HOME环境变量本身必须指向 JDK 根目录，两者不矛盾。

3.3 settings.xml 放哪：全局还是用户级

环境变量配好只是让mvn能跑，真正决定依赖从哪下载、走不走镜像的是settings.xml。3.6.2 解压后conf/下有一份全局settings.xml，用户目录~/.m2/下可以再放一份用户级配置。我的做法是：全局那份不动，用户级那份按需覆盖。原因是全局配置影响所有用户，改坏了不好回滚；用户级配置只影响自己，出问题删掉就恢复默认。

用户级配置的创建方式：

# 创建 .m2 目录（首次运行 mvn 也会自动创建） mkdir -p ~/.m2 # 从全局配置复制一份作为模板 cp /opt/apache-maven-3.6.2/conf/settings.xml ~/.m2/settings.xml

逻辑说明：Maven 启动时会先读全局settings.xml，再读用户级settings.xml，用户级的配置项会覆盖全局的同名项。所以镜像、本地仓库路径这类个性化配置放用户级最合适。复制过来之后别急着改，先确认文件编码是 UTF-8，Windows 上用记事本改容易存成 GBK，导致中文注释乱码甚至解析失败，我一般用 VS Code 或者 Notepad++ 改。

4. 配 settings.xml：本地仓库与镜像的取舍

4.1 改本地仓库路径，别让 C 盘爆掉

Maven 默认把依赖下载到~/.m2/repository，Windows 上就是C:\Users\你的用户名\.m2\repository。一个中等规模的 Java 项目，依赖拉全之后这个目录轻松上 GB，多项目并行开发时十几 GB 很常见。C 盘空间紧张的话，第一件事就是把这个路径挪走。

<!-- ~/.m2/settings.xml 中找到 localRepository 节点，取消注释并改成实际路径 --> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <!-- 本地仓库路径，Windows 用正斜杠或双反斜杠 --> <localRepository>D:/maven-repo</localRepository> </settings>

逻辑说明：localRepository是全局唯一的本地仓库，所有项目共享。路径里同样要避开空格和中文，Windows 上写D:/maven-repo比D:\maven-repo更保险，因为 XML 里反斜杠是转义字符，写单反斜杠会解析出错。改完之后，之前~/.m2/repository里已经下好的依赖不会自动迁移，要么手动拷过去，要么让它重新下。我一般会手动拷，省一次全量下载的时间。

注意：如果你同时维护多个 JDK 版本的项目，不建议给每个 JDK 配独立的本地仓库，依赖是二进制 jar，和 JDK 版本无关，共享一个仓库反而省空间。真正需要隔离的是 SNAPSHOT 依赖频繁变动的场景，那种情况用-U强制更新比换仓库更实际。

4.2 镜像配置：mirrorOf 写错会拦掉所有仓库

国内网络环境下，中央仓库直连速度不稳定，配镜像是常规操作。但mirrorOf这个参数写错，后果比不配还严重——它会把本该走其他仓库的请求也劫持过来，导致某些依赖死活下不到。

<!-- ~/.m2/settings.xml 的 mirrors 节点内 --> <mirrors> <mirror> <!-- 镜像唯一标识，随便起但要和别的 mirror 不重复 --> <id>central-mirror</id> <!-- 镜像名称，仅用于展示 --> <name>Central Mirror</name> <!-- 镜像地址，换成你实际可用的仓库地址 --> <url>https://repo.example.com/maven2</url> <!-- 关键参数：拦截哪些仓库的请求 --> <mirrorOf>central</mirrorOf> </mirror> </mirrors>

逻辑说明：mirrorOf的值决定这个镜像代理哪些仓库。写central表示只代理 id 为central的仓库，这是最保守也最安全的写法；写*表示代理所有仓库，包括项目pom.xml里自定义的私服仓库，这时候如果镜像里没有那些私服的构件，就会报「Could not find artifact」。我踩过这个坑：项目里配了公司私服，本地settings.xml又写了mirrorOf为*，结果私服依赖全部 404，排查了半天才发现是镜像把私服请求也拦了。正确做法是用external:*或者显式排除：

<!-- 代理所有外部仓库，但排除公司私服 --> <mirrorOf>external:*,!company-repo</mirrorOf>

external:*表示所有非本地、非 file 协议的仓库，!company-repo是排除指定 id。这个写法比*精细，适合既有公网镜像又有内网私服的场景。

4.3 用一条命令验证配置是否生效

改完settings.xml，不用等跑项目，直接用help:effective-settings看合并后的最终配置：

# 输出生效的 settings 配置，重点看 localRepository 和 mirrors mvn help:effective-settings

逻辑说明：这个 goal 会把全局配置和用户级配置合并后打印出来，你能直接看到localRepository最终指向哪、mirrors里实际生效的是哪几条。如果输出里没看到你改的镜像，说明文件位置放错了或者 XML 格式有问题（比如标签没闭合）。另一个常用的是help:effective-pom，看项目最终生效的 pom，排查插件版本冲突时很好用。

5. 避坑与排查：五个装 Maven 时最容易翻车的点

5.1 mvn 命令找不到，但 java 正常

现象：java -version正常输出，mvn -v报「不是内部或外部命令」或command not found。

原因：PATH里没加%MAVEN_HOME%\bin，或者加了但没生效。Windows 上常见于改完环境变量没重开 CMD 窗口，旧窗口读的还是旧PATH；Linux 上常见于改的是.bashrc但当前用的是 zsh，读的是.zshrc。

解决：先echo $PATH（Windows 用echo %PATH%）确认 Maven 的 bin 在不在里面。不在就回去检查变量名拼写，MAVEN_HOME别写成M2_HOME（3.6.2 已经不认M2_HOME了，这是 2.x 时代的变量）。在的话就重开终端，或者source对应配置文件。

5.2 编译报 source 1.6 不支持 lambda

现象：项目代码用了 JDK 8 语法，mvn compile报「lambda expressions are not supported in -source 1.6」。

原因：Maven 3.6.2 配套的maven-compiler-plugin默认source和target是 1.6，项目pom.xml里没显式指定编译版本，插件就按默认值走。

解决：在pom.xml的build/plugins里显式配编译插件版本：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.1</version> <configuration> <!-- 按项目实际 JDK 版本写，8 就写 1.8 --> <source>1.8</source> <target>1.8</target> <!-- 编码不配的话，中文注释可能编译乱码 --> <encoding>UTF-8</encoding> </configuration> </plugin>

source和target要和实际 JDK 匹配，encoding建议显式写 UTF-8，否则在 GBK 默认编码的 Windows 机器上，源码里的中文注释会出问题。

5.3 依赖下载卡住或报 501/403

现象：mvn clean install卡在 Downloading 阶段，或者报501 HTTPS Required、403 Forbidden。

原因：中央仓库早期支持 HTTP，后来强制 HTTPS，老版本 Maven 或者老settings.xml里如果还写着http://repo1.maven.org，就会被拒。3.6.2 默认的中央仓库地址已经是 HTTPS，但如果你的settings.xml是从老项目拷过来的，镜像地址可能还是 HTTP。

解决：检查settings.xml里所有url节点，确保是https://开头。另外确认镜像地址本身可用，有些内网镜像只对特定网段开放，换网络环境就 403。

5.4 本地仓库有 jar 但依然报找不到

现象：明明~/.m2/repository里能看到某个 jar，mvn还是报「Could not resolve dependencies」。

原因：最常见的是上次下载中断，目录里留了.lastUpdated文件，Maven 认为这个构件下载失败过，短期内不再重试。另一种是 jar 下了一半，文件大小不对。

解决：找到对应目录，删掉.lastUpdated文件，然后加-U强制更新：

# 删除所有失败标记文件（Linux/macOS） find ~/.m2/repository -name "*.lastUpdated" -delete # 强制更新依赖重新下载 mvn clean install -U

-U的意思是强制检查 SNAPSHOT 更新和重新尝试失败的下载，日常构建不用加，排查依赖问题时加上。

5.5 多版本 Maven 共存时版本串了

现象：明明装的是 3.6.2，mvn -v显示的却是 3.5.x 或 3.8.x。

原因：PATH里有多个 Maven 的 bin 目录，排在前面的优先级高。常见于之前装过 IDE 自带的 Maven，或者系统包管理器装过一个。

解决：which -a mvn（Windows 用where mvn）列出所有 mvn 路径，确认哪个在前。要么调整PATH顺序把 3.6.2 提前，要么把旧的删掉。IDE 里还要单独检查：IntelliJ IDEA 的 Maven 设置里可以指定Maven home directory，如果那里配的是 bundled 版本，命令行和 IDE 用的就不是同一个 Maven，构建结果可能不一致。

6. 装完怎么验证：从空项目到一次完整构建

环境配完，别拿现成项目直接跑，先用一个最小项目验证整条链路通不通。这一步能提前暴露 JDK、仓库、镜像、插件四层的问题，比在真实项目里排查省事得多。

6.1 用 archetype 生成一个空项目

# 在临时目录下生成一个最小 Java 项目 cd /tmp mvn archetype:generate \ -DgroupId=com.example.demo \ -DartifactId=demo-app \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DarchetypeVersion=1.4 \ -DinteractiveMode=false

逻辑说明：archetype:generate是 Maven 的项目骨架生成器，maven-archetype-quickstart是最简单的 Java 项目模板。-DinteractiveMode=false关掉交互式提问，适合脚本化执行。这一步会触发插件下载，如果镜像配对了，几秒到几十秒完成；如果卡住，回去看第 5.3 节的镜像问题。生成完cd demo-app，目录里应该有pom.xml和src/main/java/com/example/demo/App.java。

6.2 跑一次 clean package 看全链路

cd demo-app # 清理、编译、打包，一条命令走完 mvn clean package

预期输出末尾是BUILD SUCCESS，target/目录下生成demo-app-1.0-SNAPSHOT.jar。这条命令覆盖了依赖解析、编译、测试、打包四个阶段，任何一环配置有问题都会在这里暴露。如果报编译错误，看第 5.2 节的编译版本；如果报依赖下载失败，看第 5.3 和 5.4 节；如果测试阶段失败但代码没问题，可能是 surefire 插件版本和 JDK 不匹配，在pom.xml里锁一个稳定版本即可。

6.3 验证清单：四项都过才算装好

这四项里，前三项是静态检查，最后一项是动态验证。我见过不少人前三项都过，最后一项卡在测试插件上，原因是maven-surefire-plugin默认版本太老，和 JDK 8 之后的某些特性不兼容，在pom.xml里显式锁 2.22.2 或更高版本就能解决。

从那以后我每次装完 Maven，都会先跑一遍这个空项目构建，再碰真实项目。因为空项目排除了业务代码的干扰，出问题一定是环境本身，定位起来快得多。这套流程在 3.6.2 上验证过多次，换到 3.8.x 也基本通用，差别只在个别插件的默认版本。希望帮到你。

本文还有配套的精品资源，点击获取