企业官网建设流程全解析

简介：Apache Maven 3.6.2 的官方二进制压缩包，面向 Java 开发者与项目构建初学者，用于在本地快速搭建标准化的依赖管理与构建环境，解决手动管理 jar 包、构建流程不统一的问题。压缩包共 68 个文件，约 8.77MB，以 42 个 jar 核心库与插件依赖为主体，辅以 so、dll、jnilib 等本地库文件适配多平台，另有 cmd、mvn 等启动脚本、xml 与 conf 配置文件及 license、notice 许可说明，目录按 boot、bin、lib、conf 组织，结构清晰。已有 323 人学习下载。包内保留完整的 POM 解析、依赖解析与插件机制组件，读者可直接解压配置环境变量后使用 mvn 命令完成编译、测试、打包与部署，并借助 settings.xml 定制本地仓库与镜像，是理解 Maven 构建体系、排查依赖冲突的实用基础工具。

1. 从一台新机器说起：为什么我还在用 apache-maven-3.6.2.zip

上周给一台重装过的构建机补环境，JDK 装完、JAVA_HOME配好，敲下mvn -v直接报「命令未找到」。这台机器要跑的是几个老项目的打包流水线，构建脚本里写死了maven-compiler-plugin的旧版本，用 Maven 3.9 反而会触发插件解析告警。所以我没犹豫，直接翻出 apache-maven-3.6.2.zip 这个免安装压缩包重新铺一遍。Maven 的环境搭建本身不复杂，但版本选错、MAVEN_HOME和M2_HOME混用、settings.xml放错位置，这三件事足够让一个新手在「mvn 不是内部或外部命令」和「Could not resolve dependencies」之间来回折腾一下午。这篇笔记面向的是要在一台干净机器上把 Maven 3.6.2 装到能正常拉依赖、能跑mvn package的开发者，尤其是维护老项目、需要固定构建工具版本的那批人。下面按「装什么 → 怎么装 → 怎么配 → 坏了怎么救 → 怎么验证」走一遍，命令都可以直接抄。

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

2.1 Maven 3.6.2 对 JDK 的要求

Maven 本身是 Java 程序，启动靠JAVA_HOME指向的 JDK。Maven 3.6.2 要求 JDK 7 及以上，但实际项目里我一般配 JDK 8，原因是 3.6.x 这一代对 JDK 8 的兼容最稳，很多老项目的maven-compiler-plugin也是按 1.8 写的。如果你机器上装的是 JDK 11 或 17，Maven 3.6.2 能启动，但编译老项目时可能碰到source option 1.8 is no longer supported这类报错，那是编译器插件的问题，不是 Maven 装坏了。先确认 JDK：

# 确认当前 JDK 版本与安装路径 java -version echo $JAVA_HOME # Linux / macOS # Windows 在 cmd 里用 echo %JAVA_HOME%

输出里java version "1.8.0_xxx"说明 JDK 8 在位；JAVA_HOME必须指向 JDK 根目录（含bin/java的那一层），不能指到bin里面，这是最常见的第一个坑。如果JAVA_HOME为空，先补上再往下走，Maven 启动脚本第一件事就是读它。

2.2 目录规划：解压位置决定后续维护成本

apache-maven-3.6.2.zip 是免安装包，解压即用，所以「装在哪」就是唯一需要决策的事。我一般遵循两条：路径不含空格和中文，且所有构建工具集中在一个父目录下。常见做法是 Linux/macOS 放/opt/maven/apache-maven-3.6.2，Windows 放D:\tools\maven\apache-maven-3.6.2。这样以后升版本只需并列放一个新目录，改环境变量即可回滚，不用卸载重装。

提示：不要把 Maven 解压到Program Files这类带空格的路径，启动脚本里路径未加引号时会被截断，表现为莫名其妙的ClassNotFoundException。

2.3 版本取舍：3.6.2 与新版差在哪

有人会问，为什么不直接上最新的 3.9.x。差别主要在三点：一是 3.9 对maven-compiler-plugin的默认行为和插件校验更严，老项目里那些没写版本号的插件声明容易报警；二是 3.6.2 的settings.xml结构简单，镜像和仓库配置的容错高；三是很多公司内网的私服文档、构建镜像都是按 3.6.x 写的。如果你的项目是新起的、依赖都走现代版本，用新版没问题；但维护存量项目、需要和流水线保持一致时，3.6.2 是更省心的选择。这也是我这次直接拿 apache-maven-3.6.2.zip 的原因。

3. 解压与系统变量：把 mvn 命令接进 PATH

3.1 Linux / macOS 下的解压与软链

拿到 zip 后先解压到规划好的目录，再做一个版本无关的软链，这样以后换版本只改软链指向，环境变量不用动：

# 创建父目录并解压 sudo mkdir -p /opt/maven sudo unzip apache-maven-3.6.2.zip -d /opt/maven # 建立软链，maven 始终指向当前使用版本 sudo ln -sfn /opt/maven/apache-maven-3.6.2 /opt/maven/current # 验证目录结构，bin 下应有 mvn 脚本 ls /opt/maven/current/bin

unzip -d指定解压目标，解压后目录名就是压缩包内的apache-maven-3.6.2；ln -sfn里的-n很关键，它保证重复执行时把软链当文件替换而不是钻进目录里建链，这是运维脚本里反复踩过的细节。ls那一步是确认mvn、mvn.cmd、m2.conf都在，缺了说明压缩包不完整，重新下载即可。

3.2 写环境变量：MAVEN_HOME 与 PATH

Maven 启动脚本会读MAVEN_HOME（部分老脚本也认M2_HOME），并把$MAVEN_HOME/bin加进 PATH。Linux/macOS 下写进 shell 配置文件：

# 追加到 ~/.bashrc 或 ~/.zshrc export MAVEN_HOME=/opt/maven/current export PATH=$MAVEN_HOME/bin:$PATH # 让配置立即生效 source ~/.bashrc

MAVEN_HOME指向软链目录，PATH把bin前置，保证mvn优先命中我们装的这份。这里有个取舍：M2_HOME是 Maven 1/2 时代的变量，3.x 已不推荐，但某些 IDE 和旧脚本仍会读它，稳妥做法是同时导出export M2_HOME=$MAVEN_HOME，成本为零，能省掉一类「IDE 找不到 Maven」的排查。

3.3 Windows 下的变量配置

Windows 用系统属性里的环境变量界面，或者用setx命令行：

:: 设置 MAVEN_HOME，注意不要带尾部反斜杠 setx MAVEN_HOME "D:\tools\maven\apache-maven-3.6.2" /M :: 把 bin 追加进 PATH（/M 表示系统级，需管理员权限） setx PATH "%PATH%;%MAVEN_HOME%\bin" /M

setx写入的是持久变量，当前已打开的终端不会生效，必须新开一个窗口再验证。/M写系统级变量，不加则只对当前用户生效，多人共用的构建机建议加。尾部不要带反斜杠，否则拼出来的PATH会出现\\bin，虽然多数情况能跑，但排查时容易看花眼。

3.4 第一次验证：mvn -v 该看到什么

变量配完，新开终端执行：

mvn -v

正常输出包含三行关键信息：Apache Maven 3.6.2、Java version: 1.8.0_xxx、Java home: ...。如果版本号对但 Java home 指向了 JRE 而不是 JDK，说明JAVA_HOME配错了，后面编译会失败。如果提示命令未找到，先echo $PATH看bin有没有进去，再确认 shell 配置文件是否被当前终端加载（zsh 用户写进.bashrc是不生效的，这是新手高频翻车点）。

4. settings.xml 配置：镜像、本地仓库与私服

4.1 配置文件放哪：用户级优先于安装级

Maven 的配置有两层：安装目录下conf/settings.xml是全局的，~/.m2/settings.xml是用户级的，后者优先。我一般只改用户级，原因是全局文件在升级或重装时容易被覆盖，而且多用户机器上各人需求不同。首次使用可以先复制一份模板：

# 创建 .m2 目录并复制模板 mkdir -p ~/.m2 cp /opt/maven/current/conf/settings.xml ~/.m2/settings.xml

复制而不是直接改全局文件，等于给自己留了后悔药：配置改坏了，删掉用户级文件就回到默认行为，不用去翻安装目录。Windows 下对应路径是C:\Users\你的用户名\.m2\settings.xml。

4.2 配镜像：让依赖下载不再卡住

默认中央仓库在境外，拉依赖慢是常态。常见做法是在settings.xml的<mirrors>里配一个内网或公共镜像：

<mirrors> <mirror> <!-- 镜像唯一标识，自定义即可 --> <id>internal-mirror</id> <!-- 拦截所有仓库请求 --> <mirrorOf>*</mirrorOf> <name>internal mirror</name> <url>https://mirror.example.internal/repository/maven-public/</url> </mirror> </mirrors>

mirrorOf写*表示拦截所有仓库请求，包括项目pom.xml里声明的仓库，适合内网统一出口的场景；如果只想拦中央仓库，写central更保守，避免把项目自带的特殊仓库也劫持掉。id要和后面<servers>里的认证 id 对上，否则私服要账号密码时会 401。改完不需要重启，下次mvn执行即生效。

4.3 本地仓库位置与私服认证

本地仓库默认在~/.m2/repository，磁盘紧张时可以挪到数据盘：

<localRepository>/data/m2/repository</localRepository>

挪位置后记得把旧仓库内容迁过去，否则等于全部重新下载。私服需要认证时，在<servers>里加：

<servers> <server> <!-- 与 mirror 的 id 保持一致 --> <id>internal-mirror</id> <username>deploy-user</username> <password>******</password> </server> </servers>

id必须和<mirror>的id完全一致，这是认证不生效最常见的原因。密码明文写在文件里不理想，合格做法是用mvn --encrypt-password生成密文再填，或者交给 CI 的密钥管理，本地开发机至少把文件权限收到 600。

4.4 一个能跑的最小 settings.xml 骨架

把上面几块拼起来，去掉注释后大致是这样，可以直接作为起点：

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"> <localRepository>/data/m2/repository</localRepository> <mirrors> <mirror> <id>internal-mirror</id> <mirrorOf>central</mirrorOf> <url>https://mirror.example.internal/repository/maven-public/</url> </mirror> </mirrors> <servers> <server> <id>internal-mirror</id> <username>deploy-user</username> <password>******</password> </server> </servers> </settings>

这份骨架只保留最必要的三块：仓库位置、镜像、认证。mirrorOf这里用central而不是*，是为了不干扰项目里可能声明的其他仓库，等确认内网出口统一后再改成*。XML 对标签顺序不敏感，但<servers>的id匹配是严格的，改完用mvn help:effective-settings可以打印合并后的最终配置，确认镜像和仓库都按预期生效。

5. 避坑与排查：五条踩过的真实记录

5.1 现象：mvn 命令找不到，但变量明明配了

原因通常是 shell 配置文件写错文件，或者PATH拼接时把$PATH写在了前面导致覆盖。解决：echo $PATH确认bin在列，echo $MAVEN_HOME确认非空；zsh 用户检查.zshrc，登录 shell 和非登录 shell 加载的文件不同，必要时在.zprofile里也补一份。

5.2 现象：依赖下载卡在 Downloading 不动

原因多为镜像地址不可达或mirrorOf把私服也劫持了。解决：先用curl -I探一下镜像 URL 是否返回 200，再把mirrorOf从*收窄到central试一次；如果项目pom.xml里声明了公司私服，*会让请求全部打到镜像，私服里的包自然拉不到。

5.3 现象：编译报 source option 1.8 不再支持

原因不是 Maven 装错，而是 JDK 版本高于项目编译目标，且maven-compiler-plugin没锁版本。解决：确认JAVA_HOME指向 JDK 8；若必须用高版本 JDK，在pom.xml里显式声明maven-compiler-plugin版本并配<release>8</release>，不要依赖默认值。

5.4 现象：settings.xml 改了但完全不生效

原因通常是放错位置，或者文件名拼成了setting.xml。解决：用mvn help:effective-settings看实际加载的配置，输出里会显示用户级和全局级文件的合并结果；确认路径是~/.m2/settings.xml，Windows 下注意用户目录可能被重定向到网络盘。

5.5 现象：本地仓库里出现 lastUpdated 文件，重试也不下载

原因是之前某次下载中断留下了失败标记，Maven 默认在一天内不重试。解决：删掉对应目录下的*.lastUpdated文件再执行，或者加-U参数强制更新快照；批量清理可以用find ~/.m2/repository -name "*.lastUpdated" -delete，执行前确认路径没写错。

6. 装完怎么验证：三条命令确认这套环境真能跑

装完不验证等于没装。我一般按「版本 → 配置 → 真实构建」三层来确认，每层都有明确的通过标准，任何一层不过就停在那里排查，不要带着问题往下走。

第一层是版本与 JDK 绑定，执行mvn -v，通过标准是版本号显示 3.6.2、Java home 指向 JDK 根目录。这一层不过，后面全是白搭。第二层是配置生效，执行mvn help:effective-settings，重点看输出里的localRepository是不是你设的路径、mirrors里是不是你配的镜像。这一步能提前暴露「文件放错位置」这类静默失败，比等到拉依赖时才报错省时间。

第三层是真实构建，找一个最小项目跑一遍完整生命周期：

# 生成一个最小工程骨架 mvn archetype:generate -DgroupId=com.example.demo \ -DartifactId=demo-app -Dversion=1.0.0 \ -DinteractiveMode=false # 进入目录执行打包，观察依赖下载与编译 cd demo-app && mvn clean package

archetype:generate会从镜像拉模板，能顺带验证镜像通不通；-DinteractiveMode=false关掉交互，适合脚本化验证。mvn clean package的通过标准是最后出现BUILD SUCCESS，且target/下生成了 jar。如果卡在下载，回到第 5 章排查镜像；如果编译报错，回到 5.3 看 JDK 与插件版本。

还有一个小技巧：验证完把mvn -v的输出和effective-settings的关键段落存一份到机器上的环境记录里，下次换机器或同事接手，直接对照，不用重新猜这套环境当时是怎么配的。我吃过一次亏，一台构建机的镜像配置被后来的人改过，排查了半天才发现是mirrorOf从central变成了*，从那以后我每次装完 Maven 都强制走一遍这三层验证，并把输出留档。希望帮到你。

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