mac系统中Java项目环境配置与问题解决全记录｜环境准备篇：JDK与Maven安装配置

原创

肥晨

发布于 2026-07-30 09:52:56

5780

问题场景

$ mvn --version
zsh: command not found: mvn

根本原因

系统缺少Java开发工具包（JDK）和Maven构建工具。

解决方案

1.1 安装JDK 17（ARM64架构）

# 从AWS Corretto下载（或使用Temurin）
curl -L -o ~/jdk.tar.gz "https://corretto.aws/downloads/latest/amazon-corretto-17-aarch64-macos-jdk.tar.gz"

# 解压到指定目录
mkdir -p ~/java-temurin
tar -xzf ~/jdk.tar.gz -C ~/java-temurin --strip-components=1

1.2 安装Maven 3.9.8

# 下载Maven
curl -L -o ~/maven.zip "https://archive.apache.org/dist/maven/maven-3/3.9.8/binaries/apache-maven-3.9.8-bin.zip"

# 解压
unzip ~/maven.zip -d ~/
mv ~/apache-maven-3.9.8 ~/maven

1.3 配置环境变量

在 ~/.zshrc 中添加：

# Java环境
export JAVA_HOME=$HOME/java-temurin/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# Maven环境
export MAVEN_HOME=$HOME/maven
export PATH=$MAVEN_HOME/bin:$PATH

1.4 使配置生效

source ~/.zshrc
# 验证安装
java -version
mvn -version

💡 小贴士：如果使用Intel芯片Mac，请下载x86_64版本；Windows用户可考虑使用Chocolatey或Scoop包管理器。

📖 写在前面

当你从Git仓库克隆下一个Java项目，满怀期待地执行 mvn clean install 时，却被 zsh: command not found: mvn 泼了一盆冷水——这是每个Java开发者都可能遇到的场景。

本文作为系列第一篇，将极其详细地讲解如何在macOS（ARM64架构）上从零开始配置Java开发环境，包括JDK的选型与安装、Maven的配置、环境变量的原理与设置，以及常见问题的深度剖析。

本文目标：让你不仅知道"怎么配"，更理解"为什么这么配"。

第一章：准备工作 —— 了解你的系统

1.1 确认系统架构

在执行任何安装之前，首先需要确认你的Mac芯片类型，这直接决定下载哪个版本的JDK。

# 在终端执行
uname -m

输出解读：

arm64 → Apple Silicon芯片（M1/M2/M3/M4系列）
x86_64 → Intel芯片

为什么这很重要：ARM64和x86_64的JDK版本不通用，下载错误会导致无法执行或性能问题。

1.2 检查是否已有Java环境

# 检查Java版本
java -version

# 检查JAVA_HOME是否已设置
echo $JAVA_HOME

# 检查系统路径中的Java
which java

如果已有旧版本（如Java 8或Java 11），建议先确认项目要求。本项目需要 Java 17。

1.3 关于Shell的选择

macOS默认从bash切换到了zsh，本文所有配置基于zsh。确认你的Shell类型：

echo $SHELL
# 输出应为 /bin/zsh 或 /bin/bash

第二章：JDK 17 安装详解

2.1 JDK发行版的选择 —— 为什么选Corretto？

市面上主流的JDK发行版对比：

发行版	提供商	特点	适用场景
Amazon Corretto	AWS	免费、长期支持、经过生产环境验证	通用首选
Eclipse Temurin	Eclipse基金会	开源、社区活跃、AdoptOpenJDK继任者	社区推荐
Oracle OpenJDK	Oracle	官方版本、无商业支持	开发测试
Oracle JDK	Oracle	商业版本、付费支持	企业生产
Azul Zulu	Azul	性能优化、多种GC选择	特殊场景
GraalVM	Oracle	支持AOT编译、多语言	微服务/原生镜像

本教程选择 Amazon Corretto 17，原因：

✅ 完全开源免费
✅ AWS生产环境大规模使用，稳定性有保障
✅ 提供ARM64原生版本
✅ 更新周期与OpenJDK同步

2.2 下载JDK 17

方式一：命令行下载（推荐，省去浏览器操作）

# 创建存放目录
mkdir -p ~/java-temurin

# 下载Corretto 17 ARM64版本（永久有效链接）
curl -L -o ~/jdk-17-arm64.tar.gz \
  "https://corretto.aws/downloads/latest/amazon-corretto-17-aarch64-macos-jdk.tar.gz"

# 如果是Intel芯片，使用：
# curl -L -o ~/jdk-17-x64.tar.gz \
#   "https://corretto.aws/downloads/latest/amazon-corretto-17-x64-macos-jdk.tar.gz"

下载文件说明：

文件名：amazon-corretto-17-aarch64-macos-jdk.tar.gz
大小：约160-180MB
格式：tar.gz压缩包

方式二：浏览器手动下载

访问 https://docs.aws.amazon.com/corretto/latest/corretto-17-ug/downloads-list.html
找到对应版本：
- 操作系统：macOS
- 架构：ARM64 或 x64
- 格式：tar.gz
下载到 ~/Downloads 目录

2.3 解压与安装

# 方式一：命令行下载后的解压
tar -xzf ~/jdk-17-arm64.tar.gz -C ~/java-temurin --strip-components=1

# 方式二：浏览器下载后的解压
tar -xzf ~/Downloads/amazon-corretto-17-aarch64-macos-jdk.tar.gz \
  -C ~/java-temurin --strip-components=1

参数解释：

-xzf：解压（x）gzip压缩（z）tar包（f）
-C ~/java-temurin：解压到目标目录
--strip-components=1：去除顶层目录，直接将内容解压到目标文件夹

为什么不安装到系统目录（如/Library/Java）？undefined安装到用户目录 ~/ 的好处：不需要sudo权限可以同时管理多个版本卸载时直接删除文件夹即可不会影响系统其他用户

2.4 验证JDK安装

# 检查目录结构
ls -la ~/java-temurin/
# 应看到 bin/ conf/ include/ jmods/ legal/ lib/ man/ release 等目录

# 验证可执行文件
~/java-temurin/Contents/Home/bin/java -version
# 输出示例：
# openjdk version "17.0.11" 2024-04-16 LTS
# OpenJDK Runtime Environment Corretto-17.0.11.9.1 (build 17.0.11+9-LTS)
# OpenJDK 64-Bit Server VM Corretto-17.0.11.9.1 (build 17.0.11+9-LTS, mixed mode, sharing)

第三章：Maven 安装与配置

3.1 Maven是什么？

Apache Maven是一个项目管理与构建工具，主要功能：

依赖管理：自动下载项目所需的第三方库（jar包）
标准化构建：编译、测试、打包、部署的一键化操作
生命周期管理：clean → compile → test → package → verify → install → deploy

3.2 为什么选择Maven 3.9.8？

本项目使用Maven 3.9.8，原因：

与Spring Boot 3.x兼容
支持Java 17
稳定版本，经过广泛测试

3.3 下载Maven

方式一：命令行下载

# 创建目录
mkdir -p ~/maven

# 下载Maven 3.9.8
curl -L -o ~/maven-3.9.8-bin.zip \
  "https://archive.apache.org/dist/maven/maven-3/3.9.8/binaries/apache-maven-3.9.8-bin.zip"

# 解压（zip格式用unzip）
unzip ~/maven-3.9.8-bin.zip -d ~/
mv ~/apache-maven-3.9.8/* ~/maven/
rm -rf ~/apache-maven-3.9.8

方式二：浏览器下载

访问 https://maven.apache.org/download.cgi
找到 apache-maven-3.9.8-bin.zip 链接
下载后解压到 ~/maven

3.4 Maven目录结构说明

~/maven/
├── bin/                 # 可执行脚本（mvn, mvnDebug等）
│   └── mvn              # 主命令脚本
├── boot/                # 类加载器
├── conf/                # 配置文件
│   ├── settings.xml     # 全局配置文件（重要！）
│   └── toolchains.xml   # 工具链配置
├── lib/                 # Maven核心库
└── LICENSE, NOTICE...   # 法律文件

3.5 配置Maven镜像加速（中国大陆用户必做）

Maven默认从中央仓库（https://repo.maven.apache.org/maven2/）下载依赖，国内访问速度慢且不稳定。

创建或修改 ~/.m2/settings.xml：

mkdir -p ~/.m2

在 ~/.m2/settings.xml 中写入：

<?xml version="1.0" encoding="UTF-8"?>
<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 
          http://maven.apache.org/xsd/settings-1.0.0.xsd">
    
    <!-- 配置阿里云镜像 -->
    <mirrors>
        <mirror>
            <id>aliyun-maven</id>
            <mirrorOf>central</mirrorOf>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
        <!-- 备用镜像：华为云 -->
        <mirror>
            <id>huaweicloud</id>
            <mirrorOf>central</mirrorOf>
            <name>华为云镜像</name>
            <url>https://mirrors.huaweicloud.com/repository/maven/</url>
        </mirror>
    </mirrors>
    
    <!-- 设置本地仓库位置（可选） -->
    <localRepository>${user.home}/.m2/repository</localRepository>
    
    <!-- 配置JDK版本（可选，帮助编译时指定版本） -->
    <profiles>
        <profile>
            <id>jdk-17</id>
            <activation>
                <activeByDefault>true</activeByDefault>
                <jdk>17</jdk>
            </activation>
            <properties>
                <maven.compiler.source>17</maven.compiler.source>
                <maven.compiler.target>17</maven.compiler.target>
            </properties>
        </profile>
    </profiles>
</settings>

镜像配置说明：

<mirrorOf>central</mirrorOf>：拦截所有对中央仓库的请求
<url>：阿里云仓库地址，速度可达10MB/s+
多个镜像可以按优先级配置，第一个生效

第四章：环境变量深度解析

4.1 什么是环境变量？

环境变量是操作系统级别的命名参数，Shell和应用程序可以通过它们获取配置信息。

变量名	作用	示例值
`JAVA_HOME`	Java安装根目录	`~/java-temurin/Contents/Home`
`MAVEN_HOME`	Maven安装根目录	`~/maven`
`PATH`	可执行文件搜索路径	`$JAVA_HOME/bin:$MAVEN_HOME/bin:/usr/bin`
`CLASSPATH`	Java类路径	通常不需要手动设置

4.2 Shell配置文件详解

macOS下zsh的配置文件加载顺序：

文件	加载时机	建议用途
`/etc/zshenv`	每次启动，系统级	系统管理员配置，不建议修改
`~/.zshenv`	每次启动，用户级	最小化配置，用于PATH等
`~/.zprofile`	登录Shell	登录时执行一次
`~/.zshrc`	交互式Shell	最常用，别名、提示符、环境变量
`~/.zlogin`	登录Shell之后	登录后执行
`~/.zlogout`	退出Shell时	清理操作

实用建议：大多数情况下，把环境变量配置在 ~/.zshrc 中即可。

4.3 配置`~/.zshrc`

打开配置文件：

# 使用任意编辑器
vim ~/.zshrc
# 或
nano ~/.zshrc
# 或
code ~/.zshrc  # 使用VS Code

添加以下内容：

# ============================================
# Java & Maven 环境配置
# 作者: [你的名字]
# 日期: 2026-07-26
# ============================================

# ---------- JDK 17 配置 ----------
export JAVA_HOME=$HOME/java-temurin/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# ---------- Maven 3.9.8 配置 ----------
export MAVEN_HOME=$HOME/maven
export PATH=$MAVEN_HOME/bin:$PATH

# ---------- 其他可选配置 ----------
# 设置Maven内存（解决大项目编译内存不足）
export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"

# 添加自定义别名
alias mci='mvn clean install'
alias mcp='mvn clean package'
alias mcc='mvn clean compile'
alias mvnt='mvn test'

# 打印环境信息（可注释掉）
echo "✅ JAVA_HOME: $JAVA_HOME"
echo "✅ MAVEN_HOME: $MAVEN_HOME"

4.4 配置生效与验证

# 方式一：重新加载配置（推荐）
source ~/.zshrc

# 方式二：新开终端窗口（自动加载）

# 验证环境变量
echo $JAVA_HOME
# 输出: /Users/你的用户名/java-temurin/Contents/Home

echo $MAVEN_HOME
# 输出: /Users/你的用户名/maven

echo $PATH
# 应看到 $JAVA_HOME/bin 和 $MAVEN_HOME/bin 在路径中

# 验证命令可用
java -version
javac -version
mvn -version

4.5 常见环境变量问题排查

问题1：`source ~/.zshrc` 后还是没有效果

排查步骤：

# 检查文件是否真的被读取
echo "test" >> ~/.zshrc && source ~/.zshrc
# 如果终端输出 "test"，说明读取成功

# 检查是否有语法错误
zsh -n ~/.zshrc

# 查看实际PATH值
echo $PATH | tr ':' '\n' | grep -E 'java|maven'

问题2：`java -version` 显示旧版本

原因：系统路径 /usr/bin/java 可能指向旧版本。

解决方法：

# 查看java命令的实际位置
which java
# 如果输出 /usr/bin/java，需要调整PATH顺序

# 确保JAVA_HOME/bin在PATH最前面
export PATH=$JAVA_HOME/bin:$PATH
# 注意：$JAVA_HOME/bin 放在 $PATH 前面

问题3：每次新开终端都要`source ~/.zshrc`

原因：可能使用的不是zsh，或者配置文件路径不对。

# 确认当前Shell
echo $SHELL

# 如果是bash，应配置 ~/.bash_profile 或 ~/.bashrc
# 如果是zsh，配置 ~/.zshrc

# 设置默认Shell为zsh（可选）
chsh -s /bin/zsh

第五章：多版本JDK管理（进阶）

5.1 为什么需要多版本？

场景	需要的Java版本
当前项目	Java 17
遗留项目维护	Java 8 或 Java 11
学习新特性	Java 21 (LTS)
Android开发	Java 11 或 17

5.2 使用jEnv管理多版本

安装jEnv

# 使用Homebrew安装
brew install jenv

# 配置jEnv到zshrc
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
source ~/.zshrc

添加JDK版本

# 添加已安装的JDK
jenv add ~/java-temurin/Contents/Home

# 查看已添加的版本
jenv versions

# 设置全局版本
jenv global 17.0

# 设置当前目录版本（进入项目目录后执行）
jenv local 17.0

注意：如果使用jEnv，需要移除 ~/.zshrc 中手动设置的 JAVA_HOME，由jEnv自动管理。

第六章：实战验证 —— 编译项目

6.1 克隆项目并首次构建

# 进入项目目录
cd ~/Desktop/FeiChenERP/backend

# 查看pom.xml确认项目信息
cat pom.xml | grep -E "<groupId>|<artifactId>|<version>" | head -10

# 首次构建（下载所有依赖）
mvn clean compile

# 观察下载过程
# [INFO] Downloading from aliyun-maven: https://maven.aliyun.com/repository/public/...
# 如果看到类似输出，说明镜像配置成功

6.2 构建过程中的常见问题

错误信息	原因	解决方法
`UnsupportedClassVersionError`	Java版本不匹配	检查项目pom.xml中的`<maven.compiler.source>`是否为17
`Could not resolve dependencies`	依赖下载失败	检查网络，或切换到备选镜像
`OutOfMemoryError`	内存不足	设置`MAVEN_OPTS="-Xmx2048m"`
`Plugin execution not covered`	插件版本问题	更新插件版本或在pom中指定

6.3 打包成可执行Jar

# 跳过测试打包（加快速度）
mvn clean package -DskipTests

# 构建成功后查看
ls -la target/*.jar
# 预期输出：openerp-backend-1.0.0.jar

# 验证jar包是否可执行
java -jar target/openerp-backend-1.0.0.jar --version
# 如果输出版本信息，说明jar包构建成功

6.4 Jar包命名规则解析

openerp-backend-1.0.0.jar 的命名结构：

部分	来源	示例
`openerp-backend`	`<artifactId>`	pom.xml中定义
`1.0.0`	`<version>`	pom.xml中定义
`.jar`	打包格式	Maven默认生成

注意：实际文件名可能与你预期的不同（如原以为openerp-1.0.0.jar），应以target目录实际生成的为准。

第七章：深度问题排查

7.1 `zsh: command not found: mvn` 完整排查清单

# 1. 检查文件是否存在
ls -la ~/maven/bin/mvn

# 2. 检查文件是否可执行
chmod +x ~/maven/bin/mvn

# 3. 检查MAVEN_HOME是否正确
echo $MAVEN_HOME
# 应输出 ~/maven（不含bin）

# 4. 检查PATH是否包含MAVEN_HOME/bin
echo $PATH | grep maven

# 5. 直接执行完整路径测试
~/maven/bin/mvn -version

# 6. 检查zshrc是否正确加载
grep -E "MAVEN_HOME|maven" ~/.zshrc

# 7. 检查是否有其他配置覆盖
grep -r "MAVEN_HOME" ~/.zprofile ~/.zshenv 2>/dev/null

7.2 `Unable to access jarfile` 深度解析

# 1. 确认target目录存在
ls -la target/

# 2. 如果target不存在，执行构建
mvn package

# 3. 如果target存在但没有jar包，检查pom.xml的打包配置
grep -A5 "<packaging>" pom.xml

# 4. 检查是否有多个jar包
find target -name "*.jar" -type f

# 5. 检查jar包是否损坏
file target/openerp-backend-1.0.0.jar
# 正常输出: Zip archive data

# 6. 尝试用绝对路径执行
java -jar $(pwd)/target/openerp-backend-1.0.0.jar

7.3 环境变量优先级

命令行临时设置（最高优先级）
    ↓
Shell配置文件 (~/.zshrc, ~/.bashrc)
    ↓
系统级配置 (/etc/profile, /etc/environment)
    ↓
默认值（最低优先级）

调试技巧：

# 查看所有环境变量
env | sort

# 查看特定变量来源
which java
type java

# 查看命令执行详情
set -x
mvn -version
set +x

第八章：最佳实践与效率提升

8.1 创建一键环境配置脚本

setup-java-env.sh：

#!/bin/bash
# Java开发环境一键配置脚本
# 使用方法: chmod +x setup-java-env.sh && ./setup-java-env.sh

set -e

echo "🚀 开始配置Java开发环境..."

# 1. 创建目录
mkdir -p ~/java-temurin ~/maven ~/.m2

# 2. 下载JDK 17
if [ ! -d "$HOME/java-temurin/Contents/Home" ]; then
    echo "📥 下载JDK 17..."
    curl -L -o /tmp/jdk.tar.gz \
        "https://corretto.aws/downloads/latest/amazon-corretto-17-aarch64-macos-jdk.tar.gz"
    tar -xzf /tmp/jdk.tar.gz -C ~/java-temurin --strip-components=1
    rm /tmp/jdk.tar.gz
fi

# 3. 下载Maven
if [ ! -f "$HOME/maven/bin/mvn" ]; then
    echo "📥 下载Maven..."
    curl -L -o /tmp/maven.zip \
        "https://archive.apache.org/dist/maven/maven-3/3.9.8/binaries/apache-maven-3.9.8-bin.zip"
    unzip -q /tmp/maven.zip -d /tmp/maven-extract
    mv /tmp/maven-extract/apache-maven-3.9.8/* ~/maven/
    rm -rf /tmp/maven.zip /tmp/maven-extract
fi

# 4. 配置环境变量
if ! grep -q "JAVA_HOME" ~/.zshrc; then
    echo "📝 配置环境变量..."
    cat >> ~/.zshrc << 'EOF'

# Java & Maven Environment
export JAVA_HOME=$HOME/java-temurin/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH
export MAVEN_HOME=$HOME/maven
export PATH=$MAVEN_HOME/bin:$PATH
export MAVEN_OPTS="-Xmx2048m"
EOF
fi

# 5. 配置Maven镜像
if [ ! -f ~/.m2/settings.xml ]; then
    echo "📝 配置Maven镜像..."
    cat > ~/.m2/settings.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<settings>
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <mirrorOf>central</mirrorOf>
            <name>阿里云镜像</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
    </mirrors>
</settings>
EOF
fi

# 6. 激活配置
source ~/.zshrc

echo "✅ 配置完成！"
echo "JDK版本: $(java -version 2>&1 | head -1)"
echo "Maven版本: $(mvn -version 2>&1 | head -1)"

8.2 日常开发常用命令速查

# 清理并编译
mvn clean compile

# 清理并打包（跳过测试）
mvn clean package -DskipTests

# 清理并安装到本地仓库
mvn clean install

# 只运行测试
mvn test

# 查看依赖树
mvn dependency:tree

# 查看有效配置
mvn help:effective-pom

# 快速修复依赖问题
mvn dependency:purge-local-repository

8.3 IDEA中配置本机JDK/Maven

如果使用IntelliJ IDEA：

配置JDK：
- File → Project Structure → SDKs
- + → Add JDK → 选择 ~/java-temurin/Contents/Home
配置Maven：
- IntelliJ IDEA → Settings → Build, Execution, Deployment → Build Tools → Maven
- Maven home path: ~/maven
- User settings file: ~/.m2/settings.xml
- Local repository: ~/.m2/repository
配置Runner：
- 在Maven设置中 → Runner
- VM Options: -Xmx2048m
- JRE: 选择JDK 17

第九章：总结与下一步

本章节要点回顾

知识点	关键命令/文件	核心理解
JDK安装	`~/java-temurin/`	选择Corretto，安装到用户目录
Maven安装	`~/maven/`	版本3.9.8，配置阿里云镜像
环境变量	`~/.zshrc`	JAVA_HOME + MAVEN_HOME + PATH
配置生效	`source ~/.zshrc`	新开终端自动加载
验证安装	`java -version`, `mvn -version`	确认版本正确
项目构建	`mvn clean package -DskipTests`	生成可执行jar包

下一篇文章预告

本文解决了"工具层"的配置问题，让项目能够编译打包。但启动运行时会遇到：

🔴 Communications link failure —— MySQL未安装
🔴 Connection refused:6379 —— Redis未安装

下一篇将详细讲解：

MySQL 8.0的安装、初始化、密码设置
数据库的创建与SQL脚本导入
Redis的安装与配置
Spring Boot应用启动参数详解

📚 附录

A. 参考文献与资源

B. 环境配置清单（检查用）

# 拷贝以下命令执行，一次性检查所有配置
echo "=== 系统信息 ===" && uname -a && \
echo "=== Shell ===" && echo $SHELL && \
echo "=== JAVA_HOME ===" && echo $JAVA_HOME && \
echo "=== MAVEN_HOME ===" && echo $MAVEN_HOME && \
echo "=== Java版本 ===" && java -version && \
echo "=== Maven版本 ===" && mvn -version && \
echo "=== PATH中的Java/Maven ===" && which java && which mvn

C. 常见错误码速查

错误码/信息	含义	快速解决
`command not found`	命令未找到	检查PATH配置
`Permission denied`	权限不足	`chmod +x` 添加执行权限
`Connection timed out`	网络超时	检查代理或更换镜像
`No compiler is provided`	缺少JDK	检查JAVA_HOME指向正确
`invalid flag: --release`	JDK版本过低	升级到JDK 17+

本文档持续更新中，如有问题欢迎讨论交流。

您好，我是肥晨。
欢迎关注我获取前端/AI学习资源，日常分享技术变革，生存法则；行业内幕，洞察先机。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

java