
## 引言：为什么 JDK 配置总让人头疼？


你是否遇到过以下情况？


- 新建项目卡在 **“Project SDK is not defined”**？

- 代码中 `java.lang.String` 报红，提示 **“Cannot resolve symbol”**？

- 明明装了 JDK 21，IDEA 却识别不到？

- 多模块项目中，有的模块用 JDK 17，有的用 JDK 25，混乱不堪？

- Maven/Gradle 构建成功，但 IDEA 运行时报错？


这些问题的根源，往往不是 JDK 没装好，而是 **IntelliJ IDEA 的 JDK 配置层级没搞清楚**。

本文将**系统性梳理 IDEA 中 JDK 配置的 5 种核心方式**，覆盖从全局默认、项目级、模块级到构建工具联动的完整链路，并特别适配 **JDK 25（2025 年 9 月发布的最新 LTS 版本）** 和 **IntelliJ IDEA 2026.1** 的最新特性。


----

## 一、前置知识：IDEA 中 JDK 配置的三层模型


在深入操作前，必须理解 IDEA 的 **JDK 配置分层结构**：


|层级|作用|配置入口|是否继承|
|:-:|:-:|:-:|:-:|
|**1. Platform Settings (Global SDKs)**|全局 JDK 仓库，注册所有可用 JDK|`File → Project Structure → Platform Settings → SDKs`|—|
|**2. Project SDK**|整个项目默认 JDK，影响新模块和 IDE 工具链|`File → Project Structure → Project Settings → Project`|是（模块可继承）|
|**3. Module SDK**|单个模块实际使用的 JDK（优先生效）|`File → Project Structure → Project Settings → Modules → [Module] → Dependencies`|否|

>✅ **关键原则**：**Module SDK > Project SDK > Global SDK 列表**。只有先在 Global 中注册 JDK，才能在 Project/Module 中选择它。


----

## 二、5 种 JDK 配置方式详解（附图+避坑指南）


### 方式 1️⃣：全局注册 JDK（Global SDK Registration）


这是**所有配置的前提**。若未在此注册，后续无法选择。

**适用场景**：首次使用 IDEA，或新增了一个本地 JDK（如刚下载 JDK 25）。
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/27e5587b607412ebd463a18c5f743932.png)
可以按上图一步步地下载自己所需的jdk版本

**操作步骤**：


1. 打开 `File → Project Structure`（快捷键 `Ctrl+Alt+Shift+S`）

2. 左侧选择 **Platform Settings → SDKs**

3. 点击 `+` 号 → 选择 **JDK**

4. 浏览到 **JDK 安装根目录**（⚠️ 不是 `bin` 子目录！）
	- Windows: `C:\Program Files\Java\jdk-25`
	- macOS: `/Library/Java/JavaVirtualMachines/jdk-25.jdk/Contents/Home`
	- Linux: `/usr/lib/jvm/jdk-25`

![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/0323eb34be963aebc5410ad6e940b245.png)

**✅ 验证成功**：列表中出现 `21` 或 `openjdk-21`。

>🔥 **避坑提示**：  
- 若点击 `+` 无反应，检查 JDK 目录是否包含 `lib`、`include`、`jmods` 等子目录——这说明你选错了路径。  
- IDEA 2026 支持自动检测已安装 JDK（需开启 `Settings → Build → Build Tools → JDK Detection`）。


----

### 方式 2️⃣：设置项目级默认 JDK（Project SDK）


**适用场景**：新建项目，或统一整个项目的 JDK 版本。

**操作步骤**：


1. `File → Project Structure`

2. 左侧选择 **Project Settings → Project**

3. 在 **Project SDK** 下拉框中选择已注册的 JDK（如 `21`）

4. **Project language level** 通常自动匹配，也可手动调整（如选 `21 (Preview) - Records, Sealed Classes...`）


**效果**：
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/92639504c4f51b46175334a70835a710.png)

- 新建的模块**默认继承此 JDK**
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/3046e97ada5baa07ebb2d4be3dedc98c.png)
- IDEA 的代码分析、语法高亮、重构等按此版本进行

- 运行不指定模块的程序时使用此 JDK


>⚠️ **注意**：Project SDK **不等于** 实际编译/运行 JDK！它只是“默认值”，模块可覆盖。


----

### 方式 3️⃣：为单个模块指定 JDK（Module SDK）


**适用场景**：多模块项目（如微服务架构），各服务需不同 JDK；或主模块用 JDK 25，测试模块用 JDK 21。

**操作步骤**：


1. `File → Project Structure`

2. 左侧选择 **Project Settings → Modules**

3. 选中目标模块（如 `infra-open-api`）
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/e452f4a898e99afb9e82a25bc99f1db0.png)
4. 切换到 **Dependencies** 标签页
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/516a5ec5a054a4b3c6412bc56840795e.png)
5. 在 **Module SDK** 下拉框中选择特定 JDK（可与 Project SDK 不同）
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/2188456a614653267d09a39f0d540c96.png)

**✅ 验证**：右下角状态栏显示当前文件所属模块的 JDK 版本。

>🔥 **高级技巧**：
勾选 **Inherit project compile output path** 可统一输出目录；取消勾选可为模块单独设置 `out` 路径。


----

### 方式 4️⃣：配置新建项目的默认 JDK（Default for New Projects）


**适用场景**：希望以后所有新项目**自动使用 JDK 21**，无需每次手动设置。

**操作步骤**：


- **Windows/Linux**: `File → New Projects Settings → Structure for New Projects`
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/0549defc9cdc06babd28f633d6b04df2.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/e4325fbe07f1c2061e4e756f7778b125.png)
- **macOS**: `IntelliJ IDEA → Preferences for New Projects → Project Settings → Project`


然后设置 **Project SDK** 为 `21`。

>💡 此设置仅影响**新建项目**，不影响已有项目。


----

### 方式 5️⃣：通过构建工具（Maven/Gradle）自动同步 JDK


**适用场景**：团队协作，确保所有开发者环境一致；避免手动配置遗漏。

#### ▶ Maven 项目


在 `pom.xml` 中声明 Java 版本：

```
<properties>
    <maven.compiler.source>25</maven.compiler.source>
    <maven.compiler.target>25</maven.compiler.target>
    <maven.compiler.release>25</maven.compiler.release>
</properties>
```
然后右键项目 → **Maven → Reload project**，IDEA 会**自动更新 Project & Module SDK**。

#### ▶ Gradle 项目


在 `build.gradle` 中：

```
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}
```
或传统方式：

```
sourceCompatibility = '25'
targetCompatibility = '25'
```
点击 **Reload Gradle Project** 即可同步。

>✅ **优势**：版本信息写入代码库，新人克隆即用，杜绝“在我机器上能跑”。


----

## 三、JDK 25 特别支持说明（2026 年最新）


根据 Oracle 官方公告，**JDK 25 于 2025 年 9 月 16 日正式发布**，是继 JDK 21 后的**新长期支持（LTS）版本**，提供至少 8 年商业支持。

**IntelliJ IDEA 2026.1 已全面支持 JDK 25**，包括：


- 语法高亮：Records、Sealed Classes、Pattern Matching 等新特性

- 调试器：支持虚拟线程（Virtual Threads）和结构化并发（Structured Concurrency, JEP 505 第五次预览）

- 性能分析：针对 String 性能优化的 Profiler 适配


>📌 **建议**：生产环境可逐步迁移至 JDK 25；学习/实验项目可直接使用。


----

## 四、常见问题排查清单


|问题现象|可能原因|解决方案|
|:-:|:-:|:-:|
|“Project SDK is not defined”|未设置 Project SDK|按方式 2 设置|
|代码报红但 Maven 能编译|Module SDK 未同步|按方式 3 检查模块 JDK|
|JDK 列表为空|未在 Global 注册|按方式 1 添加|
|切换 JDK 后仍用旧版本|缓存未刷新|`File → Invalidate Caches → Invalidate and Restart`|
|无法选择 JDK 25|IDEA 版本过低|升级至 **IntelliJ IDEA 2025.3 或更高**|


----

## 五、最佳实践建议


1. **统一管理**：团队项目务必通过 **Maven/Gradle 声明 JDK 版本**，避免手动配置差异。

2. **命名规范**：在 Global SDKs 中重命名 JDK 为 `OpenJDK 25 (Temurin)`、`Oracle JDK 21` 等，便于识别。

3. **定期清理**：删除不再使用的旧 JDK（如 JDK 8），减少下拉列表干扰。

4. **验证脚本**：在项目根目录放一个 `CheckJDK.java`：```
	public class CheckJDK {
	    public static void main(String[] args) {
	        System.out.println("Java Version: " + System.getProperty("java.version"));
	        System.out.println("Java Home: " + System.getProperty("java.home"));
	    }
	}
	```
	运行即可确认实际运行时 JDK。


----

## 结语


JDK 配置看似简单，实则涉及 IDEA 的核心项目模型。掌握这 **5 种配置方式**，你不仅能解决 99% 的环境问题，还能在多版本、多模块项目中游刃有余。

>**记住**：**Global 注册 → Project 默认 → Module 覆盖 → 构建工具同步**，四步走，稳如泰山。


**下期预告**：《IntelliJ 系列④：深度解析 Virtual Threads + Structured Concurrency 在 IDEA 中的调试技巧》


----

**参考资料**：


- [JetBrains 官方文档：SDK 配置](https://www.jetbrains.com/help/idea/sdk.html)

- [Oracle: Java 25 Release Announcement](https://www.oracle.com/cn/news/announcement/oracle-releases-java-25-2025-09-16/)

- IntelliJ IDEA 2026.1 What’s New


>👉 **互动**：你在配置 JDK 时还遇到过哪些奇葩问题？欢迎评论区交流！

代码中 java.lang.String 报红，提示 “Cannot resolve symbol”？

万字详解IntelliJ IDEA配置JDK 的5种方式:从 JDK8到JDK25全版本(2026 最新版)-IntelliJ 系列

JDK 配置看似简单，实则涉及 IDEA 的核心项目模型。掌握本文这 **5 种配置方式**，你不仅能解决 99% 的环境问题，还能在多版本、多模块项目中游刃有余。

开发工具

编程语言

后端

IntelliJ IDEA JDK配置全攻略：5种方式解决项目环境问题，涵盖JDK25最新支持。从全局注册到模块级设置，详解多版本管理技巧，提供Maven/Gradle自动同步方案，附带常见问题排查清单。掌握分层配置原则，彻底解决SDK未定义、代码报红等环境问题。

微服务架构

调试器

Windows

Linux

Java

2026采购季 | AI焕新·智启新局

tcap

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

万字详解IntelliJ IDEA配置JDK 的5种方式:从 JDK8到JDK25全版本(2026 最新版)-IntelliJ 系列-腾讯云开发者社区-腾讯云

万字详解IntelliJ IDEA配置JDK 的5种方式:从 JDK8到JDK25全版本(2026 最新版)-IntelliJ 系列

万字详解IntelliJ IDEA配置JDK 的5种方式:从 JDK8到JDK25全版本(2026 最新版)-IntelliJ 系列

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐