IntelliJ IDEA

2026-04-01

本文聚焦 Nebula 项目的实际开发场景，介绍 IDEA 的项目导入、环境配置、必备插件和高效使用技巧，略过与项目无关的通用功能介绍。

一、推荐版本

使用 IntelliJ IDEA Ultimate 2024.1 及以上版本，Community 版本缺少 Spring Boot Run Dashboard、数据库工具等功能，不推荐用于 Nebula 后端开发。

前端开发（nebula-web）使用 WebStorm 或 IDEA Ultimate 均可。

二、导入 Nebula 项目

Nebula 各子项目（nebula-boot、nebula-auth、nebula-system 等）是独立的 Gradle 多模块项目，每个项目单独 clone 后单独导入 IDEA。

步骤：

File → Open，选择项目根目录（含 settings.gradle 的那层）
IDEA 识别到 Gradle 项目后，点击右下角弹出的 Load Gradle Project 或打开右侧 Gradle 面板 → 刷新
等待依赖下载完成（首次可能需要几分钟，依赖从内网 Nexus 拉取）

注意： 不要用 File → New → Project from Existing Sources 方式导入，否则 Gradle 模块识别会不完整。

同时开发多个子项目

如需同时在一个 IDEA 窗口中查看 nebula-boot 和 nebula-system，可以用 Attach Gradle Project 功能：

打开 Gradle 面板（右侧边栏 Gradle 图标）
点击 + 号 → 选择另一个项目的 build.gradle 文件
两个项目的模块会在同一个 Project 视图中并排展示

三、JDK 与 Gradle 配置

3.1 配置 JDK 17

Project SDK：File → Project Structure → Project → SDK → 选择 JDK 17（需提前安装）

Gradle JVM：File → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVM → 选择 JDK 17

两处都要配置，否则可能出现编译时用对了 JDK，但 Gradle 同步时报版本不兼容的问题。

3.2 配置内网 Nexus 仓库

Nebula 的依赖（nebula-boot、nebula-support 等）发布在内网 Nexus，不能从 Maven Central 拉取。

Gradle 配置文件已包含仓库地址（settings.gradle），IDEA 同步时会自动使用。但若网络环境需要代理，在 ~/.gradle/gradle.properties 中配置：

# Nexus 认证（如需要）
nexusUsername=your-username
nexusPassword=your-password

# HTTP 代理（如需要）
systemProp.http.proxyHost=proxy.yourcompany.com
systemProp.http.proxyPort=8080

3.3 Gradle 同步失败处理

同步失败时依次检查：

右下角 Build Output 查看具体报错
确认 VPN / 内网连接正常，能访问 Nexus
清除本地缓存后重试：~/.gradle/caches/ 删除对应版本缓存
在 Gradle 面板点击 Reload All Gradle Projects

四、必装插件

在 File → Settings → Plugins 中搜索安装：

插件	用途
Lombok	必装。不装则 `@Data`、`@Builder` 等注解编译报错，整个项目无法运行
MapStruct Support	必装（后端）。IDEA 识别 MapStruct 的 `@Mapping` 注解，支持跳转和自动补全
MyBatisX	推荐（后端）。Mapper 接口与 XML 之间跳转，SQL 语句高亮
SonarLint	推荐。实时代码质量扫描，提前发现潜在问题
GitToolBox	推荐。在编辑器行末显示 Git blame 信息，方便追溯代码变更
Vue - Official	必装（前端）。Vue 3 + TypeScript 语法支持
Prettier	推荐（前端）。代码格式化，与团队保持一致

Lombok 插件开启注解处理器

安装 Lombok 插件后，还需要启用注解处理：

File → Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable annotation processing ✅

五、项目跑起来之前的检查项

5.1 配置本地启动的 application 文件

Nebula 服务使用多 profile 配置，本地开发使用 dev profile。

在 IDEA 的 Run Configuration 中设置：

Active profiles: dev

或在 application.yml 确认：

spring:
  profiles:
    active: dev

5.2 配置 Run Dashboard

Spring Boot 项目多了之后，建议开启 Run Dashboard 统一管理：

View → Tool Windows → Services（或快捷键 Alt+8）

所有 Spring Boot 运行实例、端口、日志都在这里集中查看。

5.3 启动参数配置（内存）

Nebula 服务依赖较多，本地启动建议给 JVM 分配足够内存，避免 OOM：

Run Configuration → Modify options → Add VM options：

-Xms256m -Xmx1024m

六、高频快捷键速查

以下是 Nebula 项目开发中最常用的快捷键（macOS 版，Windows 将 ⌘ 换成 Ctrl，⌥ 换成 Alt）：

导航类

快捷键	功能
`⌘ + N`	全局搜索类名（Go to Class）—— 最常用，快速定位 Controller/Service
`⌘ + Shift + N`	全局搜索文件名
`⌘ + ⌥ + N`	全局搜索 Symbol（方法、字段名）
`⌘ + E`	最近打开的文件
`⌘ + B`	跳转到定义（Go to Definition）
`⌘ + U`	跳转到父类/接口定义
`⌥ + F7`	查找所有使用处（Find Usages）—— 重构前必查
`⌘ + F12`	查看当前类的方法结构

编辑类

快捷键	功能
`⌘ + D`	复制当前行
`⌘ + Backspace`	删除当前行
`⌥ + ↑ / ↓`	按语法结构扩展/缩小选择范围
`⌘ + /`	行注释/取消注释
`⌘ + ⌥ + L`	格式化代码（Format Code）—— 提交前必跑
`⌘ + ⌥ + O`	优化 import（删除无用 import）
`Shift + F6`	重命名（Rename Refactoring）—— 自动更新所有引用
`⌘ + ⌥ + M`	提取方法（Extract Method）

调试类

快捷键	功能
`⌘ + F8`	在当前行设置/取消断点
`F8`	单步跳过（Step Over）
`F7`	单步进入（Step Into）
`⇧ + F8`	跳出当前方法（Step Out）
`F9`	恢复运行（Resume）
`⌥ + F8`	在调试中执行表达式（Evaluate Expression）

七、常见问题处理

Q1：Gradle 同步后，包找不到（红色报错）

多模块项目中，有时 IDEA 无法自动识别某个子模块。解决方式：

Gradle 面板 → 点击 Reload All Gradle Projects
若还是报红：File → Invalidate Caches → Invalidate and Restart

Q2：运行时报 `Cannot find symbol`，但代码看起来没问题

通常是 Lombok 或 MapStruct 生成的代码未被 IDEA 识别：

确认 Enable annotation processing 已勾选
Build → Rebuild Project 重新全量编译

Q3：修改了 `build.gradle` 依赖，但代码还是用老版本

点击 Gradle 面板的 Reload 按钮，或右键项目 → Gradle → Reload Gradle Project，强制同步依赖。

Q4：启动时报 `Port already in use`

查找并杀掉占用端口的进程：

# macOS / Linux
lsof -i :8080
kill -9 <PID>

# 或直接用 IDEA 的 Services 面板，停掉之前没关干净的实例