摘要

对于刚接触开源或刚开始做 Java 开发的新手来说，第一道门槛往往不是代码本身，而是环境配置。Git 怎么装？JDK 用哪个版本？Maven 怎么配？Docker 为什么装完还不能用？这些问题如果没人带，很容易在第一步就卡很久。本文基于 Mac 环境，按照实际开发和开源参与的常用路径，详细整理 Git、JDK、Maven、Docker 的安装与配置步骤，并补充常见踩坑点，尽量做到新手照着一步步操作也能配好。

前言

很多人刚接触开源或者刚开始学开发时，最先遇到的问题并不是“代码不会写”，而是：

• 工具装不上

• 装好了命令不能用

• 版本不对

• 环境变量没生效

• Docker 明明装了，但运行还是报错

• Git 可以打开，但命令行里找不到

这些问题看起来不难，但如果是第一次配置，很容易一环卡一环。

我自己平时主要在 Mac 上做 Java 开发，也会用 Git、Maven、Docker 这些工具。回头看，其实开发环境搭建最重要的不是“装了多少工具”，而是：

先把最常用、最基础、最容易影响后续开发的工具配好。

所以这篇文章我就按一个比较实用的顺序来整理：

1. Git

2. JDK

3. Maven

4. Docker

这几个配好以后，基本就具备了做 Java 开发和参与很多开源项目的基础环境。

一、先说结论：一套最实用的 Mac 开发环境清单

如果你是新手，不想一开始就装太多东西，那我建议先装这 4 个：

• Git：代码版本管理，参与开源几乎绕不开

• JDK：Java 开发运行环境

• Maven：Java 项目依赖管理和构建工具

• Docker：本地跑服务、数据库、开源项目时很常用

如果是更完整一点的开发环境，还可以后续再补：

• IDE（IntelliJ IDEA / VS Code）

• Homebrew

• 数据库客户端

• API 调试工具

但这篇先聚焦最核心的四个。

二、开始之前：先确认你的 Mac 是什么芯片

这一步看起来简单，但其实很重要。

因为现在很多 Mac 是 Apple Silicon，也就是 M 系列芯片，比如：

• M1

• M2

• M3

而有些教程是按老款 Intel Mac 写的。

如果你不先搞清楚自己的机器类型，后面在安装软件时可能会遇到：

• 下载错版本

• 路径不一致

• 命令装完后找不到

• 某些依赖兼容问题

怎么看自己的芯片

点击左上角苹果图标：

关于本机

如果你看到的是：

• Apple M1 / M2 / M3 → 说明是 Apple Silicon

• Intel → 说明是 Intel Mac

为什么要先看这个

因为后面像 Homebrew 的默认安装路径，经常会不一样：

• Apple Silicon 常见路径：/opt/homebrew

• Intel 常见路径：/usr/local

虽然这篇文章尽量用通用方式写，但你最好先知道自己属于哪种机器。

三、Git 安装与配置

Git 是第一优先级工具。

因为你只要想参与开源，基本就一定会接触这些动作：

• clone 代码

• 创建分支

• 提交 commit

• 拉取最新代码

• 推送到远程仓库

• 提交 PR

所以 Git 建议最先装。

3.1 查看系统里有没有 Git

先打开终端，执行：

git --version

如果能看到类似输出：

git version 2.x.x

说明系统里已经有 Git 了。

但这里要注意一点：

有些 Mac 自带的是系统层面的 Git，不一定是你后续最想用的版本。

如果只是初学者，先能用就行；如果你后面要长期开发，建议还是装一套自己可控的版本。

3.2 推荐安装方式：用 Homebrew 安装 Git

如果你已经安装了 Homebrew，可以直接执行：

brew install git

安装完成后，再执行：

git --version

确认版本。

3.3 如果还没装 Homebrew，先装 Homebrew

Homebrew 是 Mac 上非常常用的包管理工具。

你后面装 Git、Maven 甚至很多其他工具时，都会方便很多。

安装命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，根据终端提示，把 Homebrew 加到环境变量里。

如果你是 Apple Silicon，通常是类似这样：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

然后执行：

brew --version

看到版本信息就说明安装成功了。

3.4 配置 Git 用户信息

Git 装完后，建议先把基础身份信息配一下。

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

例如：

git config --global user.name "zhangsan"
git config --global user.email "zhangsan@example.com"

查看配置是否成功：

git config --global --list

你应该能看到类似：

user.name=zhangsan
user.email=zhangsan@example.com

3.5 新手常见 Git 踩坑

1）终端里能打开 Git，但 IDEA / VS Code 识别不到

这通常是路径问题，或者 IDE 没有自动识别到 Git 可执行文件路径。

2）提交代码时报身份错误

一般就是 user.name 和 user.email 没配。

3）HTTPS 拉代码总要输入密码

现在很多代码托管平台已经不建议直接用账号密码了，通常要配：

• Token

• SSH Key

如果你后面准备长期参与开源，建议后续再单独配置 SSH Key。

四、JDK 安装与配置

如果你要做 Java 开发，JDK 肯定绕不过去。

但新手最容易纠结的问题是：

• JDK 该装哪个版本？

• JRE 和 JDK 有什么区别？

• 系统里装了多个版本怎么办？

4.1 新手先记一个结论

如果你是刚开始接触 Java 开发，或者只是先跑项目，我建议优先考虑：

• JDK 8

• JDK 17

为什么是这两个？

• 很多老项目还在用 JDK 8

• 很多新项目逐渐转到 JDK 17

• 这两个版本在实际开发里最常见

如果你已经知道目标项目要求哪个版本，那就按项目要求来。

4.2 查看系统是否已有 Java

打开终端执行：

java -version

如果系统已经安装 Java，会看到版本信息。

再执行：

javac -version

如果 javac 也有输出，说明 JDK 工具链比较完整。

4.3 推荐安装方式：用 Homebrew 安装 OpenJDK

例如安装 JDK 17：

brew install openjdk@17

安装完成后，终端一般会提示你做路径配置。

例如常见做法：

echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

然后确认版本：

java -version
javac -version

4.4 设置 JAVA_HOME

很多 Java 工具会依赖 JAVA_HOME，所以建议一起配置。

可以先查看安装路径：

/usr/libexec/java_home -V

然后把对应版本配置进环境变量，例如：

export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH

把这两行加到你的 ~/.zshrc 里：

echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 17)' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

检查：

echo $JAVA_HOME
java -version

4.5 多版本 JDK 怎么办

比如你可能有：

• 一个项目要 JDK 8

• 一个项目要 JDK 17

这时候不要慌，Mac 是可以共存多个 JDK 的。

关键是你要知道当前终端使用的是哪个版本。

可以用：

/usr/libexec/java_home -V

查看所有可用版本。

临时切换某个终端会话的 JDK：

export JAVA_HOME=$(/usr/libexec/java_home -v 8)
export PATH=$JAVA_HOME/bin:$PATH

这样只影响当前终端窗口。

4.6 JDK 常见踩坑

1）java -version有输出，但 javac -version没有

这通常说明你装的不是完整 JDK，或者 PATH 没配对。

2）IDE 里的 JDK 和终端里的 JDK 不一致

这个很常见。终端配置好了，不代表 IDEA 里自动跟着变，IDE 里还要单独检查项目 SDK。

3）Maven 编译时报版本不对

很多时候不是 Maven 坏了，而是它拿到的 JAVA_HOME 不是你以为的那个版本。

五、Maven 安装与配置

Maven 是 Java 项目里非常常用的构建工具。

很多开源 Java 项目你刚 clone 下来，第一步就是：

mvn clean install

所以 Maven 也建议尽早装好。

5.1 查看系统里有没有 Maven

执行：

mvn -version

如果能看到版本信息，说明已经装过。

如果提示找不到命令，就需要安装。

5.2 用 Homebrew 安装 Maven

brew install maven

安装完成后执行：

mvn -version

如果看到类似输出：

Apache Maven 3.x.x
Java version: 17

说明 Maven 能正常工作。

这里你还可以顺便检查 Maven 实际使用的是哪个 Java 版本。

5.3 Maven 的 settings.xml 配置

Maven 装完能用，不代表配置就完整了。

实际开发里，通常还会配一个 settings.xml 文件，比如：

• 配置本地仓库位置

• 配置镜像源

• 配置私服

• 配置认证信息

Maven 的用户级配置目录通常在：

~/.m2/

如果没有，可以自己创建。

常见文件：

~/.m2/settings.xml

5.4 一个常见的基础配置思路

新手一开始可以先只理解这两个配置。

1）本地仓库地址

例如：

<localRepository>/Users/yourname/.m2/repository</localRepository>

它表示 Maven 下载下来的依赖包放在哪。

2）镜像配置

如果你直接用默认中央仓库，有时候下载会比较慢。

所以很多人会配置镜像源。

这个属于“优化项”，不是“不配就完全不能用”，但实际体验会差很多。

5.5 Maven 常见踩坑

1）mvn -version 能运行，但项目依赖下载很慢

通常和网络、镜像源有关。

2）终端里 Maven 正常，IDE 里构建失败

可能是 IDEA 使用了自己的 Maven 配置，或者 JDK 设置不一致。

3）报 Java 版本不匹配

要重点检查：

• JAVA_HOME

• mvn -version 显示的 Java 版本

• 项目 pom.xml 里的编译版本

六、Docker 安装与配置

Docker 对现在很多开发场景都很有帮助，尤其是：

• 本地起数据库

• 启动 Redis、Nacos、MySQL、PostgreSQL 等服务

• 跑一些开源项目依赖环境

• 统一开发环境

如果你打算接触开源，Docker 很值得尽早学会。

6.1 Mac 上推荐直接安装 Docker Desktop

Mac 新手最省事的方式，一般是安装 Docker Desktop。

安装后，你会同时得到：

• Docker 引擎

• Docker CLI

• 图形化管理界面

• 一些基础容器能力

安装完成后，记得真正打开一次 Docker Desktop。

因为很多人以为“装完就能用”，其实如果 Docker Desktop 没启动，命令行里还是可能报错。

6.2 检查 Docker 是否可用

先执行：

docker --version

如果有输出，说明命令行工具已经装上了。

再执行：

docker info

如果这一步也正常输出，说明 Docker 服务也已经可用了。

你还可以跑一个测试容器：

docker run hello-world

如果能顺利跑起来，就说明 Docker 环境基本正常。

6.3 Docker Desktop 常见问题

1）命令有了，但 docker info 报错

通常是 Docker Desktop 没启动。

2）安装后提示权限相关问题

按系统提示完成授权即可。

3）拉镜像很慢

这通常不是 Docker 本身没装好，而是镜像拉取速度问题。这个在不同网络环境下差异会很大。

6.4 新手先会这几个 Docker 命令就够了

不用一上来学太多，先记住最常用的：

docker --version
docker info
docker ps
docker ps -a
docker images
docker run hello-world
docker logs 容器ID
docker stop 容器ID
docker start 容器ID
docker rm 容器ID

等你后面真正开始跑 MySQL、Redis、Nacos 之类服务时，再逐步扩展就够了。

七、环境变量到底是什么，新手怎么理解

很多新手第一次配置环境时，最容易被“环境变量”这四个字吓到。

其实你可以先把它简单理解成：

告诉终端：某个命令程序在哪、某些工具该用哪个路径。

比如：

• 配置 PATH，是为了让系统知道 java、mvn、git 这些命令去哪里找

• 配置 JAVA_HOME，是为了让 Java 相关工具知道 JDK 在哪里

如果你不配环境变量，最常见的表现就是：

• 工具明明装了，但命令找不到

• 版本不对

• 某些程序调用不到你想要的 JDK

八、我建议的新手安装顺序

如果你完全从 0 开始，我建议按这个顺序来：

第一步：Homebrew

因为它能帮你后面装很多工具。

第二步：Git

先把最基础的版本管理工具装好。

第三步：JDK

Java 项目必须依赖。

第四步：Maven

Java 项目构建和依赖下载要用。

第五步：Docker

后续跑服务、跑项目、学开源都很有帮助。

这样配下来，路径会比较清晰，不容易乱。

九、配完之后，怎么快速自检

环境装完以后，不要急着结束，最好做一遍自检。

你可以依次执行：

brew --version
git --version
java -version
javac -version
echo $JAVA_HOME
mvn -version
docker --version
docker info

如果这些命令大部分都正常，你的开发环境就已经比较完整了。

十、我自己总结的几个经验

1）不要一上来装一堆工具

先装最核心的，能跑起来最重要。

2）每装完一个工具都做一次命令验证

不要最后一起验，不然出了问题不容易定位。

3）先把终端环境配通，再去配 IDE

很多问题不是 IDEA 的问题，而是底层终端环境没配好。

4）新手最容易卡住的不是安装，而是“装完后命令找不到”

所以一定要理解一点点 PATH 和环境变量。

5）环境配置文不要只抄命令，最好知道每一步大概在做什么

哪怕现在理解得不深，也比纯复制粘贴强。

总结

对于刚接触开发或者刚想参与开源的新手来说，环境配置确实是第一道门槛。

但换个角度看，只要把最核心的几个工具先配好，后面的事情会顺很多。

这篇文章主要整理了 Mac 上最常用的四个基础开发工具：

• Git

• JDK

• Maven

• Docker

我的建议是：

先把基础工具配稳，再去跑项目、看源码、提 PR。

因为开源入门真正最怕的，不是“不会写代码”，而是第一步就被环境问题劝退。

如果你现在正准备开始自己的 Mac 开发环境搭建，希望这篇文章能帮你少踩一些坑。