macOS开发环境搭建完全指南：IntelliJ IDEA + JDK + Maven + Gradle + Node.js

黄健华Yeah

561人浏览 · 2026-03-08 03:30:00

黄健华Yeah · 2026-03-08 03:30:00 发布

作为一名开发者或DevOps工程师，在macOS上搭建开发环境是很多人的日常需求。

不同于Windows的直接下载安装向导，macOS（以及Linux这类类Unix系统）更推荐使用包管理器来统一管理开发工具。这不仅让安装更简单，也让后续的升级和卸载变得异常方便。

今天这篇文章，我将手把手带你完成macOS系统上全栈开发环境的完整配置，包括：

安装Homebrew包管理器（macOS的“应用商店”）
安装IntelliJ IDEA并导入项目
配置JDK 17并解决代码标红问题
安装Maven并验证命令行构建
安装Gradle并配置IDEA使用本地Gradle
安装Node.js + npm并运行React/Node应用

所有项目的Git仓库链接都在课程说明中，跟着步骤走，保证能成功。

一、核心原则：用包管理器安装工具

在macOS和Linux这类系统中，开发工具应该通过包管理器安装。这和Windows直接从官网下载安装向导的习惯完全不同。

包管理器的好处：

✅ 一键安装，自动处理依赖
✅ 一键升级，不用重新下载安装包
✅ 一键卸载，不留残留文件

macOS最主流的包管理器就是Homebrew，我们首先要安装它。

二、安装Homebrew包管理器

Homebrew是macOS下的命令行包管理器，相当于一个“开发工具的App Store”。

安装步骤：

打开浏览器，搜索“Homebrew”
进入官方网站（brew.sh）
复制官网提供的安装命令（是一段/bin/bash -c开头的脚本）
打开终端（Terminal），粘贴命令并回车执行
等待自动下载安装完成

安装完成后，你就可以通过brew install <工具名>来安装几乎所有的开发工具了。

三、安装IntelliJ IDEA

1. 下载安装

搜索“IntelliJ download”，进入JetBrains官网
选择免费的Community版本（付费的Ultimate版本课程不需要）
下载对应macOS的DMG安装包
双击打开DMG文件，将IntelliJ图标拖拽到旁边的Applications文件夹
安装完成，在Launchpad中就可以找到IntelliJ IDEA

2. IntelliJ基础功能

打开IntelliJ，初始界面支持三种操作：

新建项目
打开本地已有项目
从Git仓库直接拉取项目

本课程会先克隆项目到本地，再从IntelliJ打开。

四、安装Git并克隆项目

1. 安装Git

brew install git

如果之前已经安装过Git，可以跳过这一步。

2. 克隆Java Maven项目

在终端中，进入你想要存放代码的目录（例如用户根目录），执行：

git clone <Java Maven项目仓库地址>

克隆完成后，本地就会出现项目文件夹。

3. 在IntelliJ中打开项目

回到IntelliJ，选择“Open”
找到刚才克隆的项目文件夹，点击打开
IntelliJ会在后台自动加载处理所有文件

4. IntelliJ自动识别项目

导入项目后，无需手动声明项目类型——IntelliJ会自动识别这是Maven项目：

右侧可以看到Maven标签页
展开后可以看到Maven的生命周期操作（clean、compile、package等）
自动下载pom.xml中声明的所有依赖

五、配置JDK 17：解决代码标红问题

打开项目的Java文件后，你可能会看到代码有红色错误提示，同时显示"Project JDK not defined"。这是因为没有配置Java开发工具包（JDK）。

1. 通过Homebrew安装OpenJDK 17

brew install openjdk@17

等待安装完成。

2. 修复路径问题（创建符号链接）

安装完成后，执行java -version可能会提示找不到命令。这是因为Homebrew将OpenJDK安装到了自己的目录，而macOS和IntelliJ默认在另一个标准路径搜索JDK。

解决方法：创建符号链接（symbolic link），让标准路径指向Homebrew实际安装的目录。

sudo ln -sfn $(brew --prefix)/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

注意：命令中的版本号要和安装的JDK版本对应，如果你安装的是其他版本，需要相应修改。

3. 验证安装

java -version

看到正确的版本号（如openjdk version "17.x.x"），说明安装成功。

4. 在IntelliJ中配置JDK

这里有一个非常重要的区分：

Settings：IntelliJ的全局编辑器设置（影响所有项目）
Project Structure：当前项目的特定配置（JDK在这里配置）

正确步骤：

点击File → Project Structure
在"Project SDK"处点击"Add SDK" → "Add JDK"
选择JDK的安装路径（Homebrew安装的JDK一般在/Library/Java/JavaVirtualMachines/openjdk-17.jdk）
点击"Apply"和"OK"

IntelliJ会重新索引项目，代码的红色错误提示会全部消失，启动类旁边会出现绿色的运行三角按钮。

5. 运行项目验证

点击绿色运行按钮，选择运行应用。看到应用成功启动的日志输出，说明Java JDK配置正确。

六、安装Maven并验证命令行构建

在IntelliJ中能运行项目，但还需要在终端能用mvn命令，这样才能进行命令行构建。

1. 安装Maven

brew install maven --ignore-dependencies

关键点：添加--ignore-dependencies参数，是为了避免Maven依赖的其他版本OpenJDK和我们已安装的OpenJDK 17产生版本冲突。

2. 验证Maven构建

进入项目根目录（包含pom.xml的目录），执行：

mvn package

看到"BUILD SUCCESS"提示，说明Maven环境配置完成。

七、配置Gradle项目

1. 安装Gradle

brew install gradle

2. 克隆Gradle项目

git clone <Gradle项目仓库地址>

3. 配置IntelliJ使用本地Gradle

打开IntelliJ设置：File → Settings
搜索"Gradle"
在"Gradle distribution"选项中，选择"Local installation"
路径会自动识别我们刚刚安装的Gradle
点击"Apply"保存

4. 打开Gradle项目

通过File → Open打开克隆的Gradle项目
IntelliJ会自动识别Gradle项目，右侧显示Gradle标签页
后台自动下载依赖和插件，等待完成

5. 验证项目

打开Java文件，代码应该没有错误提示（JDK自动复用）
右键点击启动类，选择"Run"，应用成功启动
终端进入项目根目录，执行gradle build，看到"BUILD SUCCESSFUL"

八、配置Node.js项目

1. 安装Node.js和npm

brew install node

Node.js安装会自带npm，所以一条命令搞定。

2. 克隆Node项目

git clone <Node项目仓库地址>

3. 在IntelliJ中打开项目

Node.js项目配置比Java简单得多，不需要配置SDK。

4. 安装依赖并启动

# 进入项目中的API目录（包含package.json）
cd <项目路径>/API

# 安装依赖
npm install

# 启动应用
npm start

看到输出"server listening on port 3080"之类的信息，说明Node.js环境配置正确。

九、总结：环境配置要点速查表

工具	安装命令	关键点
Homebrew	官网复制命令	macOS包管理器的基础
IntelliJ	官网下载DMG	选择Community版本
Git	`brew install git`	代码版本管理
OpenJDK 17	`brew install openjdk@17`	需要创建符号链接修复路径
Maven	`brew install maven --ignore-dependencies`	避免JDK版本冲突
Gradle	`brew install gradle`	需在IDEA设置中配置本地安装
Node.js	`brew install node`	自带npm，无需额外配置