简介Apache Maven 3.6.3是Java生态中主流的项目构建与依赖管理工具基于POM模型实现标准化生命周期。面向需要离线搭建Maven环境、或希望快速获得可复用依赖库的Java开发者适用于内网开发、持续集成及教学实验等场景。压缩包共2000个文件体积134.84MB核心内容包括296个jar库文件、471个pom定义文件以及470个repositories仓库索引并附724个sha1校验文件用于依赖完整性验证同时携带少量dll/so/jnilib本地库和mvn、mvndebug启动脚本覆盖Windows、Linux及macOS平台。已有192人学习下载文件组织按Maven仓库结构分类便于直接解压后作为本地仓库或发行版使用。该版本优化了依赖解析与内存管理显著提升构建速度和稳定性借助内置的常用插件与中央仓库组件可快速完成项目清理、编译、测试、打包等全流程减少因网络或仓库配置带来的开发阻力。1. 为什么 2024 年了还在用 3.6.3一个稳定版本的生命力接手老项目的第一天你大概率会碰到这种场景照着网上的教程装 Maven下一步下一步出来的是最新的 3.9.x结果一执行mvn clean install要么Non-resolvable parent POM要么插件版本直接不兼容折腾一下午最后发现换回 maven 3.6.3 版本就一切正常。这不是玄学是这个版本真的太能打。3.6.3 是 3.6 系列的最后一个稳定分发版也是大量公司模板、CI 镜像和 IDEA 老版本捆绑的默认版本。这篇笔记从版本定位讲起把下载安装、settings.xml 配置、IDEA 集成和最常见的报错逐个拆开适合正在维护 JDK 8 老项目、或者照着教程配置半天没成功的入门开发者也适合想搞清楚“到底该不该升级 Maven”的团队技术负责人。2. 3.6.3 的版本定位先搞清楚它和你 JDK、IDEA 的关系2.1 Maven 版本不是越高越好3.6.3 的兼容性边界很多人有个误区以为构建工具跟开发工具一样版本越新越好。实际上 Maven 的版本升级经常带来构建行为的改变最典型的就是 3.8.1 之后对settings.xml中mirror配置加了blocked状态很多老教程里的镜像写法直接失效。3.6.3 还停留在旧行为上这也是它被长期使用的重要原因。从版本序列看3.6.3 之后官方直接跳到了 3.8.x中间的 3.7 和 3.8.0 都没有作为正式版发布。这意味着 3.6.3 是 3.6 这条线的终点站它集成了当时所有修复行为相对稳定。对团队来说只要项目里没有用到 Maven 4 的预览特性3.6.3 足够支撑日常的依赖管理和构建发布。另一个现实因素是 IDEA 的捆绑版本。过去很长一段时间里IDEA 自带的 Maven 就是 3.6.x 系列公司内部统一的开发环境、CI 上的构建镜像全都按这个版本调过。你要是贸然升级到 3.9.x最先翻车的往往不是构建本身而是 IDE 里那一堆旧插件和 Maven Runner 的兼容问题。2.2 确认你的 JDK 和 Maven 版本匹配一张对应关系表Maven 本身是 Java 程序跑在 JVM 上所以它对 JDK 版本有最低要求。3.6.3 这个版本理论上可以在 JDK 8 到 JDK 11 上正常工作日常最稳妥的组合是 JDK 8。如果你用 JDK 11 甚至 JDK 17也能跑但要注意编译插件版本和source/target参数的配合。常见的匹配关系大致是这样JDK 版本Maven 建议需要留意的地方JDK 83.6.3 首选编译插件用默认版本即可几乎无坑JDK 113.6.3 可用建议把 maven-compiler-plugin 升到 3.8.1 以上JDK 17建议 3.8.x 或更高3.6.3 下要显式指定 release否则可能编译报错判断当前环境是否匹配两条命令就够。先java -version看 JDK再mvn -v看 Maven 版本和它实际使用的 Java 版本。注意mvn -v输出里的Java version取决于JAVA_HOME环境变量不是PATH里的 java这一点很多人都搞混过。2.3 项目里到底在哪锁版本Maven 没写死是环境决定的pom.xml 里确实可以声明parent版本、插件版本但 Maven 本身的版本不是你用配置锁出来的它属于环境层。这就是为什么同一个 pom.xml在 3.6.3 上一切正常拷到 3.9.x 上就报错。我一般建议把 Maven 版本固定写进团队文档和 CI 镜像而不是在项目里做手脚。新入职的同事照着文档装 3.6.3和 CI 保持一致能省掉大量“我本地明明是好的”这类沟通成本。那些坚持用最新版的人往往要额外承担依赖解析结果变化的后果比如mvn dependency:tree的排序变了、某个传递依赖被新规则排除了这类问题排查起来特别消耗耐心。3. 安装与配置 3.6.3从压缩包到一条能用的 mvn 命令3.1 下载和部署Windows 与 macOS/Linux 的通用做法3.6.3 的获取途径一般是 Apache 官网的归档目录或者国内的开源镜像站。下载时认准apache-maven-3.6.3-bin.tar.gzmacOS/Linux和apache-maven-3.6.3-bin.zipWindows不要下src结尾的源码包那需要你自己编译。解压路径别带中文和空格这是血泪经验目录带空格会导致某些插件解析路径出错报错信息还特别隐晦。macOS 或 Linux 上我习惯把解压后的目录放到/opt/maven/下然后在~/.zshrc或~/.bash_profile里配置环境变量export M2_HOME/opt/maven/apache-maven-3.6.3 export PATH$M2_HOME/bin:$PATH export JAVA_HOME/usr/lib/jvm/java-1.8.0配置完记得执行source ~/.zshrc让变量生效然后运行mvn -v验证。这里有个关键点M2_HOME指向的是解压后的根目录不是bin目录PATH里加的是$M2_HOME/bin这两行写反了命令就找不到。JAVA_HOME 要根据你机器上实际安装的 JDK 路径改直接写死/usr/lib/jvm/java-1.8.0在很多新版系统上不存在。Windows 用户在系统属性里的“环境变量”新建M2_HOME值填解压路径再把%M2_HOME%\bin追加到Path变量末尾。配置完新开一个 cmd 窗口验证不要用已经打开的旧窗口Windows 的环境变量不会自动刷新。3.2 settings.xml 是核心配置本地仓库、阿里云镜像与 JDK 编译级别Maven 的配置文件是settings.xml它分全局和用户两级。全局的在 Maven 安装目录的conf下用户级的在~/.m2/settings.xml。用户级文件不存在时可以自己创建它的优先级高于全局配置。我统一推荐改用户级的因为换 Maven 版本时配置还能沿用。一个能直接用的最小配置长这样里面做了三件事指定本地仓库、配置阿里云镜像、声明 JDK 8 编译参数settings localRepositoryD:/dev/repo/maven-repo/localRepository mirrors mirror idaliyun-public/id mirrorOf*/mirrorOf namealiyun public/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors profiles profile idjdk8/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /profile /profiles /settingslocalRepository默认在~/.m2/repository如果你的 C 盘空间紧张改成D:/dev/repo/maven-repo这类路径能有效避免磁盘爆满。mirrorOf填*表示所有仓库请求都走阿里云这是最省心的写法如果只想让中央仓库走镜像可以填central但有些依赖只在自定义仓库里存在时*会把它们也拦到阿里云上可能 404。阿里云的public仓库聚合了 central 和 jcenter 的内容一般项目够用了。首段代码里的maven.compiler.source和maven.compiler.target是 Maven 3.1 之后推荐的写法比在 pom.xml 里配maven-compiler-plugin更简洁而且对 3.6.3 完全兼容。这样配置后mvn clean install编译出来的 class 文件就是 JDK 8 字节码放到 JDK 8 的运行时里不会报UnsupportedClassVersionError。3.3 IDEA 里指定 3.6.3版本、配置文件、Runner 三项设置在 IDEA 里打开Settings搜索Maven进入Build, Execution, Deployment Build Tools Maven。这里有三个地方必须亲手改不能偷懒设置项推荐值说明Maven home path你解压的 3.6.3 路径选到包含bin的那个目录User settings file你自己的~/.m2/settings.xmlIDEA 不会自动读取外部配置Local repository和 settings.xml 里保持一致改错会导致重新下载依赖改完这三个还有一步容易漏在Maven Runner里把JRE选成项目实际用的 JDK。IDEA 默认可能指向它自带的 JBR跟项目编译级别不一致时构建日志会先从 “cannot find symbol” 这类编译错误开始把方向带偏。设置完成后右侧 Maven 面板能看到项目展开Lifecycle双击clean再双击install首次执行会下载大量依赖。这时候重点看 IDEA 的Maven home path是否生效——在面板顶部的下拉框里会显示 Maven 版本确认是 3.6.3 而不是 IDEA 捆绑的版本。这一步验证通过说明 IDEA 侧配置结束。4. 3.6.3 的避坑记录这些报错我挨个踩过4.1 mvn 命令能跑IDEA 里却一直报 Non-resolvable parent POM现象命令行执行mvn -v正常pom.xml 的 parent 也确认存在但 IDEA 的 Maven 面板里所有模块都标红报错指向Non-resolvable parent POM for com.example:demo。原因IDEA 里 Maven 使用的 settings.xml 和命令行的不是同一个。IDEA 默认有自己的一份 settings路径和命令行用的可能不一致导致本地仓库、镜像配置全部失效parent 自然解析不到。解决按上面 3.3 小节的步骤把 IDEA 的User settings file显式指到命令行用的那个文件然后点Reload All Maven Projects。如果配置已经指对了还是报错看 IDEA 的Maven Importing里JDK for importer是否选对这个字段默认可能指向 11而项目需要 8同样会解析失败。4.2 阿里云镜像配了却还是走中央仓库认准 mirrorOf 和仓库顺序现象settings.xml 里明明配了阿里云镜像但构建日志里依然出现Downloading from central下载速度慢到让人怀疑人生。原因很多人把mirror写进了profiles里这是错误的。mirror是settings.xml根节点下的独立子节点不能嵌套在 profile 里。另一个原因是项目 pom.xml 里声明了repositories且这些 repository 的 id 和 mirror 的 id 冲突Maven 会跳过匹配的镜像。解决检查 settings.xml 的层级结构mirrors必须在settings下面直接展开和profiles平级我的习惯是先写mirrors再写profiles。另外确认mirrorOf是*而不是external:*后者对本地启动的仓库也会绕过镜像在某些场景下出现重复 download 的诡异日志。4.3 JDK 9 以上编译翻车maven-compiler-plugin 的 source/target 玄学现象JDK 8 下打包正常的项目切到 JDK 11 后执行clean install报错Error: invalid target release: 8或者一堆cannot access class ... 找不到符号。原因3.6.3 默认绑定的 maven-compiler-plugin 版本比较老对 JDK 9 的模块系统支持不够好。即使maven.compiler.source/target设了 1.8老插件在处理 JDK 11 的类库时还是会出问题。解决在 pom.xml 的build plugins里显式指定新版插件比如 3.8.1然后同时设置source1.8/source和target1.8/target。更彻底的做法是在 3.6.3 上直接加maven.compiler.release8/maven.compiler.release属性这个配置同时限制 source 和 target不会出现 JDK 编译期 API 误用的问题。4.4 依赖下载到一半失败lastUpdated 后缀文件卡住后续构建现象某个依赖第一次下载时网络超时删掉重试还是失败报错Could not resolve dependencies错误信息里带着.lastUpdated后缀的文件路径。原因Maven 下载失败后会在本地仓库生成.lastUpdated标记文件默认保留时间较长。在这个时间段内重试Maven 看到标记文件就直接判定该依赖不可用不再真正发起下载。解决找到对应仓库目录删除所有.lastUpdated和.part结尾的文件再重新跑。一条命令就能搞定find ~/.m2/repository -name *.lastUpdated -delete find ~/.m2/repository -name *.part -delete执行完重新mvn clean install依赖会重新拉取。这种问题在弱网环境下特别容易复现我的经验是配合阿里云镜像后基本不再遇到因为下载源在境内超时概率大幅降低。4.5 我有两个本地仓库怎么合并现象电脑上有两个 Maven 本地仓库比如旧的~/.m2/repository和在D:/repo的新仓库项目引用时缺依赖两个仓库里各有一半构建就是不通过。原因本地仓库的目录结构不是简单把 jar 拷到一起就能合并的。每个构件旁边有_remote.repositories文件记录着来源仓库 id直接物理合并会导致冲突而且 SNAPSHOT 版本的元数据maven-metadata-*.xml会互相污染。解决我的建议是别手动合并优先把其中一个仓库里的私有构件上传到公司私服然后清空本地仓库重新下载。如果私有构件没法上传那就用dependency:get把旧仓库的关键依赖逐个拉到新仓库里至少保证元数据是新的。最不推荐的做法是写脚本批量拷贝 jar时间省不了多少后续排错成本反而更高。5. 验证与进阶把 3.6.3 用在项目里的几个顺手技巧装好 3.6.3 之后别急着写代码先在命令行做一次最小验证。随便找个空目录放一个最简单的 pom.xml执行mvn clean install能把构建跑通说明环境基本健康。验证依赖解析是否正常用mvn dependency:tree是最直接的它能列出所有传递依赖排查冲突时先看这个再决定要不要在 pom 里加exclusions。我还有一个用了很久的习惯给 3.6.3 单独建一份带头部的 settings.xml用-s参数指定。比如同时维护 JDK 8 老项目和 JDK 17 新项目时会在~/.m2下放settings-jdk8.xml和settings-jdk17.xml内容只有编译参数不同。执行命令时这样切换mvn clean install -s ~/.m2/settings-jdk8.xml mvn clean install -s ~/.m2/settings-jdk17.xml这个习惯救过我一次。当时新项目用了 JDK 17但我忘了切 settings按默认的 JDK 8 配置跑了一遍全项目的中文字符全部乱码编译报了一百多个错。从那以后我再也不相信默认配置每次构建前先确认mvn -s用的是哪个文件IDEA 里如果两个项目同时打开也会在Maven Runner里分别指定 VM 参数和 JRE 版本。3.6.3 这个版本还会陪你走很久只要 JDK 8 的存量项目不消失它的生命周期就还在延续。如果你刚被某个报错折磨过不妨先按这篇笔记从头捋一遍环境多半能少走很多弯路。希望帮到你。本文还有配套的精品资源点击获取