配环境这件事说难不难说简单却总有人卡在最后一步。尤其是 JDK 和 Maven一个管运行、一个管依赖但凡环境变量写错一个字符后面启动项目时各种Error就能把人绕晕。这篇东西我本来是想整理给团队新人的写着写着发现很多“老手”也未必把这里面的门道摸透了所以拿出来分享给所有刚入坑 Java 开发、或者在换电脑/重装系统后需要从零搭建开发环境的朋友。先说清楚这篇能解决什么问题我会从 JDK 和 Maven 的下载安装讲起把环境变量为什么这么配、每个参数背后的原理拆开讲再重点聊聊 Maven 的settings.xml里那些真正影响日常开发速度的配置项。最后把我这几年踩过的坑、见到过的诡异报错按“从现象到根因”的排查思路完整走一遍你照着走基本能 20 分钟内把环境干干净净地搭好。1. 配置之前先搞懂 JDK 和 Maven 到底在扮演什么角色很多教程上来就让你装、让你配但如果你不清楚自己在配什么出了问题就只能靠猜。所以我先花点篇幅把两个核心概念讲透后面每一步你都会知道自己在干什么。1.1 JDK 不是 Java它是 Java 的“工具箱 运行环境”JDKJava Development Kit是 Java 开发工具包它里面塞了三样东西JVMJava 虚拟机负责把字节码翻译成当前操作系统能懂的机器指令、JREJava 运行时环境给编译好的程序跑起来用、以及一大堆开发工具最常用的就是javac编译器、jar打包工具、javadoc生成文档。打个比方JVM 是发动机JRE 是装好发动机的整车JDK 是这辆车加上全套维修工具和说明书。平时我们写代码只需要 JDK但如果只是运行一个 Java 程序装 JRE 就够了。因为 JDK 是向下兼容的JDK 17 能编译 Java 8 语法的代码只是编译目标可以调低所以开发机上装一个最新 LTS 版本 JDK 就能通吃。1.2 Maven 解决的是“依赖管理 构建自动化”Maven 的核心价值一句话就能概括帮你自动下载你项目需要的第三方 jar 包并且用统一的生命周期管理编译、测试、打包这些动作。它靠一套“坐标体系”找 jar 包——每个依赖都有一个唯一坐标比如org.springframework:spring-core:6.1.14三段分别对应 groupId组织名、artifactId项目名、version版本。这里有个新手最容易误解的点Maven 不是一个文件存放工具它是一个以pom.xml为中心的构建引擎。你项目里声明了依赖坐标Maven 会先去本地仓库默认~/.m2/repository找找不到就去中央仓库或你配置的镜像仓库下载下载后缓存到本地下次再用就直接从本地拿。所以本地仓库就是你机器上的jar 包缓存池。1.3 环境变量为什么是第一道坎环境变量本质上是操作系统提供给应用程序的一组全局键值对。Java 和 Maven 的启动脚本里会去读取JAVA_HOME、PATH这些变量来确定java 命令在哪、JDK 装在哪。配不好就直接表现为你在命令行敲java -version提示找不到命令或者 Maven 启动时报JAVA_HOME is not set。很多人配环境变量失败不是因为步骤复杂而是因为对系统变量和用户变量的作用域、以及 PATH 的解析顺序没概念。我用实际操作把这两点讲明白。2. JDK 安装版本选择、下载渠道、安装方式一次说清2.1 用哪个版本直接选 LTS不要追新JDK 的版本策略是每六个月出一个新功能版每三到六年出一个 LTS长期支持版本。对绝大多数人来说选 LTS 就够了。目前市面上主流的就是这几条线版本特点适用场景Java 8经典老将大量老项目仍用它编译运行但官方早已停止免费商用更新维护老项目、跑历史遗留代码Java 11第一个长时间支持版本引入了模块化、本地变量类型推断中等规模企业项目Java 17当前最主流的 LTSSpring Boot 3 要求的最低版本新项目首选Java 21最新 LTS引入虚拟线程、record pattern性能有明显提升新启动的项目、对并发要求高的服务我的建议简单直接新项目无脑上 JDK 17老项目维持项目原本要求的版本不要自己瞎升级。团队里不同项目可能要求不同 JDK那就在机器上装多个版本环境变量指向默认版IDE 里给每个项目单独指定版。后面我会专门讲多版本共存怎么管理。2.2 下载渠道盘点Oracle 官网、Adoptium、各云厂商镜像Oracle 官网下载需要注册账号而且 Oracle JDK 从 8u211 开始商业使用需要付费授权。很多个人开发者用它的 OpenJDK 构建版权上没问题但下载体验确实不如其他渠道。更推荐的是 Adoptium原 AdoptOpenJDK它是 Eclipse 基金会的开源项目提供完全免费的 OpenJDK 预编译包Windows 下有.msi安装包双击就能装而且自动配好环境变量对新手极其友好。国内网络环境下下载速度经常是玄学。如果你不想等可以用华为云的开源镜像站、阿里云的开发组件镜像站它们都提供 OpenJDK 各版本的二进制包速度稳定很多。顺带说一句下载 Mac 版选.pkg格式Windows 选.zip或.msiLinux 选.tar.gz最省事。2.3 安装时的三个细节直接影响后续配置第一安装路径不要带空格和中文。C:\Program Files\Java\jdk-17是好事但如果是D:\Java Development Kit\jdk在 PATH 里需要加引号才不出错脚本类的工具往往不解析引号直接报错。我会把 JDK 装到D:\Java\jdk-17这种干净路径。第二Windows 下如果用.zip解压JDK 目录只要解压出来就能用没有安装过程环境变量指过去即可。如果用.exe安装包注意安装过程中有一步会问你“是否设置 JAVA_HOME”勾上它会省很多时间。第三Mac 和 Linux 安装时路径要记清楚macOS 往往默认装在/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home这个路径很绕建议装完立刻用/usr/libexec/java_home -V命令检查实际路径。3. JDK 环境变量配置JAVA_HOME、PATH、CLASSPATH 逐个拆解3.1 Windows 三步配置法第一步右键“此电脑” → “属性” → “高级系统设置” → “环境变量”。在“系统变量”区域点“新建”变量名填JAVA_HOME变量值填你的 JDK 目录。重点来了这个路径只写到 JDK 的根目录不要带\bin。比如我的是D:\Java\jdk-17那JAVA_HOME就填D:\Java\jdk-17。第二步在系统变量里找到Path这一项双击编辑新建一条%JAVA_HOME%\bin。这一步的原理是java、javac这些命令的可执行文件都在%JAVA_HOME%\bin下面把%JAVA_HOME%\bin加入 PATH命令行里敲java时系统才能在这个路径下找到对应程序。这里有个坑如果Path里已经有一条写死的C:\Program Files\Java\jdk-17\bin而你后来改了JAVA_HOME指向另一个版本这条写死路径的优先级更高实际生效的还是旧版本。所以正确做法是只在 PATH 里保留%JAVA_HOME%\bin这一条带变量的配置其他版本相关的bin路径全部删掉。第三步验证。重新打开一个命令行窗口必须是新窗口旧窗口不会刷新环境变量依次输入java -version javac -version如果回显出版本号说明配置成功。注意java -version会把信息输出到 stderr因此你可能会看到版本号后面还有一段路径这是正常的尤其你装了多个 JDK 时那段路径能告诉你当前实际用的是哪个。3.2 关于 CLASSPATH别再配了网上很多老教程会让你新建一个CLASSPATH变量值写成.;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar。这个说法源自 JDK 1.4 时代——当时类加载默认路径不包括本地目录必须显式把当前目录.和工具 jar 包加进来。Java 9 以后整个模块化重构了这个变量已经是历史垃圾。现在的javac和java会自动处理类路径配了反而可能引发 jar 包冲突。如果您照着某种教程配了CLASSPATH建议直接删掉。这是我踩过坑之后才明白的很多时候诡异报错不是版本问题而是环境变量里多了一个不该存在的东西。3.3 macOS 和 Linux 的配置姿势macOS 下用zsh的话编辑~/.zshrc加上export JAVA_HOME$(/usr/libexec/java_home -v 17) export PATH$JAVA_HOME/bin:$PATHLinux 的 Bash 则编辑~/.bashrcexport JAVA_HOME/opt/jdk-17 export PATH$JAVA_HOME/bin:$PATH然后source ~/.bashrc让配置立即生效。多说一句macOS 的/usr/libexec/java_home能自动探测本机安装的 JDK 路径如果你装了多版本-v 17就锁定 17这种写法比写死路径更抗迁移。4. Maven 安装与配置从解压到 mvn -v 跑通4.1 下载哪个版本Maven 的版本不像 JDK 那样花样多认准3.8.x 或 3.9.x即可。3.9.6 之后的版本对 JDK 8 依然兼容对 JDK 17~21 支持得也很好。Maven 4 还在高速迭代中目前不建议在生产项目上手搓。下载渠道同样有两个选择Apache 官网的二进制包或者国内镜像的加速下载。Maven 是纯 zip 包Windows 下解压到D:\Java\apache-maven-3.9.6Linux 解压到/opt/apache-maven-3.9.6。注意目录层级——解压后你应能看到bin、conf、lib这些子目录如果看到多套了一层嵌套目录配置 MAVEN_HOME 时容易指错。4.2 MAVEN_HOME 的配置方式Maven 官方其实从 3.3 版本开始就不再强制要求MAVEN_HOME环境变量mvn脚本会自动推测自身路径。但强烈建议你还是配上理由有两个第一很多 IDE 和自动化工具的配置界面上直接认MAVEN_HOME第二未来升级 Maven 版本时只要改动环境变量值其他配置都不用动。Windows 下新建系统变量MAVEN_HOME D:\Java\apache-maven-3.9.6然后在Path里追加%MAVEN_HOME%\bin。这里和 JDK 的配置逻辑完全一样都是把可执行文件所在的bin目录暴露出来。4.3 验证回显的每个字段都很重要新开命令行窗口敲mvn -v正常输出类似Apache Maven 3.9.6 (rc-----) Maven home: D:\Java\apache-maven-3.9.6 Java version: 17.0.13, vendor: Oracle Corporation Java home: C:\Program Files\Java\jdk-17这三行信息要逐个看Maven home 应该是指向你刚才配的目录Java version 和 Java home 应该指向你 JDK 里实际的版本。如果 Java home 显示的路径和你预期不一致说明 Maven 用的是它自己检测到的 Java而不是你环境变量指定的——这种情况下后续编译 99% 会出幺蛾子。5. settings.xml 才是 Maven 配置的重头戏mvn -v跑通只是万里长征第一步。真正影响你日常开发体验的是 Maven 的conf/settings.xml。这个文件全球只有一个里面写着依赖去哪下载、下载完存哪里、用什么 JDK 编译。下面按优先级逐条讲。5.1 换掉默认本地仓库路径Maven 默认把依赖存到C:\Users\你的用户名\.m2\repository。问题来了C 盘空间吃紧时几个大型项目拉完依赖轻松上 5GB到时候清理系统盘时你哭都来不及。我习惯把本地仓库挪到单独盘符比如localRepositoryD:/Java/maven-repo/localRepositorylocalRepository标签放在settings.xml的最外层根节点settings标签下面和mirrors、profiles平级。改了之后所有项目的依赖缓存都会落到这个目录。换新电脑时把这个目录整体拷走等于把所有项目依赖打包迁移能省掉大量重新下载的时间。5.2 配置阿里云镜像彻底告别下载慢默认的中央仓库在国外国内拉依赖时断时续尤其是一些大 jar 包经常卡上十分钟最终失败。国内更稳妥的方案是配置阿里云公共仓库镜像。在settings.xml的mirrors标签下加入mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror这里有个细节值得单独讲mirrorOf的值。如果填*代表所有仓库都走镜像包括你后续在项目里配置的私有仓库——一旦私有仓库走镜像内网依赖永远拉不到那才是鬼故事。填central则只对中央仓库生效私有仓库依然直连这是更安全的做法。阿里云的repository/public聚合了中央仓库、JCenter 和 Google 的依赖绝大多数开源 jar 都能覆盖到。另外阿里云也提供repository/central和repository/gradle-plugin等细分仓库如果遇到某些特殊依赖找不到可以针对性切换。5.3 用 profile 锁定 JDK 编译版本很多项目报编译错误时会附带一句类似于 “invalid source release: 17” 的提示。这通常是因为 Maven 默认用 JDK 的主版本去编译而项目本身的目标版本更低或更高不一致。推荐在settings.xml里加一个始终激活的 profile把编译参数固定下来profile idjdk-17/id activation activeByDefaulttrue/activeByDefault jdk17/jdk /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target maven.compiler.compilerVersion17/maven.compiler.compilerVersion /properties /profileactiveByDefault为true时这个 profile 会默认激活所有项目在编译时二进制版本和代码版本统一为 17。这样即使某些项目的pom.xml没显式写编译版本Maven 也会用 17 去编译不会跑去用默认的旧 JDK。5.4 用户级与全局级配置别写错文件settings.xml分两个层级全局层在 Maven 安装目录的conf下用户层在~/.m2/下。用户层的配置会覆盖全局层。我强烈建议你改用户层的~/.m2/settings.xml——原因很简单全局层配置会跟着 Maven 安装目录转移如果哪天你升级或者搬移了 Maven 目录配置容易丢失用户层独立于安装目录重装 Maven 依然有效。首次使用时~/.m2目录并不存在直接新建即可。如果你不想手动新建可以先跑一次mvn help:effective-settingsMaven 会自动生成标准的settings.xml文件在用户目录里你再基于它修改可以减少格式错误。6. 配置失败的高频坑位与完整排查链路这一段是我积累最久的部分几乎每个来找我问环境问题的人都掉进过其中至少一个。6.1 坑位一命令行窗口没重启最常见的“配置失败”其实是命令窗口还在用旧环境。你改了环境变量系统会刷新注册表但已打开的终端进程不会自动重新读取。所以配完环境变量必须关掉所有命令行窗口重新打开一个新的再去验证。如果你开着 IDEA 的终端面板同样要把整个 IDEA 重启因为 IDE 内部的终端环境在启动时就固定了。6.2 坑位二JAVA_HOME 指向到了 jreWindows 装 JDK 时安装包可能同时生成了一个jre子目录。有人图省事把JAVA_HOME指向了C:\Program Files\Java\jre1.8.0结果java -version正常javac -version却提示找不到命令。因为 JRE 里只有运行时没有编译器。排查时用echo %JAVA_HOME%看输出如果发现路径里带jre改回 JDK 根目录即可。6.3 坑位三PATH 里多个 Java 版本打架机器上一堆项目装着 JDK 8、11、17想切换默认版本的时候发现怎么改JAVA_HOME都不生效。原因基本出在 PATH 的顺序上Path是从左到右依次查找的如果在%JAVA_HOME%\bin前面有一条写死的C:\Program Files\Java\jdk-8\bin那系统永远先用 8 的 java。处理时必须把 PATH 里所有硬编码的 Java 相关路径删干净只保留%JAVA_HOME%\bin。要切换版本时改JAVA_HOME的值即可。如果你用的是 IDE可能还需要在 IDE 设置里单独指定项目 SDK。6.4 坑位四mvn -v 提示 JAVA_HOME 错误Maven 跑不起来报错JAVA_HOME is defined incorrectly或者Error: JAVA_HOME is not defined correctly。这句话的重点在correctly——Maven 会检查JAVA_HOME指向的目录下有没有bin/java可执行文件。如果你把JAVA_HOME指向了 JDK 的父目录或者路径末尾多了个反斜杠、空格都会触发这个错误。另外macOS 路径容易指到.jdk/Contents/Home之下的目录少写一层都会失败。用echo %JAVA_HOME%或echo $JAVA_HOME打印出来目测一遍再去资源管理器/终端里确认该路径下确实存在bin/java。6.5 坑位五IDEA 里用的不是命令行那套配置命令行mvn -v一切正常IDEA 里 Maven 窗口却疯狂报错。因为 IDEA 中有独立的 Maven 配置它不读取环境变量里的 MAVEN_HOME你在 IDEA 的 Settings → Build → Build Tools → Maven 里看到的是它自己自动探测到的一套。正确做法把 Maven home path 手动指向你装的 Maven 目录User settings file 指向你改过的那份~/.m2/settings.xmlLocal repository 会和 settings 里指定的保持同步。改完后 IDEA 右下角会提示重新导入点确认刷新。7. 进阶实操多版本 JDK 切换的正确姿势前面反复提到多版本共存这里给一套我实践过很久的可行方案Windows 和 mac 都覆盖到。Windows 下我从不靠改名切换 JDK而是写一个批处理文件switch-jdk.batecho off set /p versionEnter JDK version (8/11/17/21): if %version%17 set JAVA_HOMED:\Java\jdk-17 if %version%8 set JAVA_HOMED:\Java\jdk-8 set PATH%JAVA_HOME%\bin;%PATH% java -version双击运行输入版本号回车当前命令行窗口的 Java 版本立刻切换。但这个方案只影响当前会话新开的窗口还是默认版本。所以我会把系统环境变量JAVA_HOME设成最常用的 17其他版本按需切换。macOS 下更简单/usr/libexec/java_home -V列出了所有已安装的 JDK配合jenv或直接在.zshrc里动态设置alias java8export JAVA_HOME$(/usr/libexec/java_home -v 1.8) alias java17export JAVA_HOME$(/usr/libexec/java_home -v 17)需要哪个版本在命令行直接敲java17当前终端会话就切过去了。8. 最后一点个人体会配置 JDK 和 Maven 这件事90% 的时间不是花在装上而是花在定位问题上。我见过太多人照着教程一步步来最后卡在一个空格、一个斜杠、或者一个没有重启的窗口上然后开始怀疑人生。其实只要你理解了环境变量的查找机制知道JAVA_HOME是指向根目录而不是bin 目录理解 Maven 的依赖仓库分本地和远程两层绝大多数报错都能一眼看穿根源。还有个小建议环境配好之后把settings.xml和 JDK 版本信息记到团队的 README 里。现在很多项目换个人接手第一周都在折腾环境其实就是缺一份完整的配置说明。你花十分钟把这几步写清楚对后面每个人都是实打实的省钱。