大家好，我是 lazy，一名大二科班学生

摘要

在学习 Java 的过程中，很多同学都会遇到 IDEA 中代码突然爆红的问题。比如 import 语句爆红、类名爆红、注解爆红、Cannot resolve symbol、package does not exist、No SDK、src 不变蓝等。对于初学者来说，这些红色提示看起来很吓人，但实际上很多时候并不是代码本身写错了，而是 JDK、Maven、项目目录、源码目录或 IDEA 缓存没有配置好。本文将结合 Java 初学者常见场景，总结 IDEA 中 Java 项目代码爆红的常见原因和解决方法。

关键词

IDEA、Java、代码爆红、Cannot resolve symbol、JDK 配置、Maven 依赖、Sources Root、Java 初学者

一、前言

很多同学刚开始学习 Java 时，一打开老师发的项目、网上下载的源码，或者同学传来的压缩包，就发现 IDEA 里面到处都是红色。最常见的情况是 import 爆红、类名爆红、注解爆红，甚至整个 src 文件夹都看起来不正常。

看到代码爆红时，不要马上觉得是自己代码写错了。IDEA 的红色提示代表“当前环境下无法正确识别这段代码”，原因可能是代码错误，也可能是环境配置问题。尤其是初学阶段，很多爆红其实都和项目配置有关。

本文会按照实际排查顺序，从 JDK、源码目录、Maven、项目结构、包名、缓存等方面进行总结，帮助初学者快速判断问题原因。

图1 IDEA 中 Java 代码爆红的常见表现示意图

二、先判断：代码爆红一定是代码错了吗

答案是不一定。代码爆红大致可以分成两类：一类是真正的代码语法错误，比如少写分号、括号不匹配、类名写错；另一类是项目环境没有配置好，比如没有 JDK、依赖没有下载、src 没有被识别为源码目录。

如果只是某一行代码爆红，可以先检查语法。如果是整个项目大面积爆红，就更应该优先检查环境配置，而不是一行一行改代码。

常见的大面积爆红包括：import 全部爆红、Spring 注解爆红、String 和 System 等基础类异常、Maven 依赖爆红、项目没有运行按钮、Problems 面板出现大量 Cannot resolve symbol。

三、原因一：JDK 没有配置

Java 项目运行必须依赖 JDK。如果 IDEA 没有配置 JDK，项目就无法正常编译，代码中很多基础类也可能无法识别。新手导入项目后出现大面积爆红，最先应该检查的就是 JDK。

在 IDEA 中依次点击 File -> Project Structure -> Project，查看 Project SDK。如果这里显示 No SDK，说明当前项目没有配置 JDK。

解决方法是点击 Add SDK，选择本机已经安装好的 JDK 目录。例如 JDK 17 常见路径为 C:\Program Files\Java\jdk-17 或 D:\Java\jdk-17。配置完成后点击 Apply，再点击 OK。

图2 IDEA 中 Project SDK 未配置时容易导致代码爆红

需要注意的是，JRE 和 JDK 不是一回事。学习 Java 开发时应该配置 JDK，而不是只配置运行环境。现在很多新项目会使用 JDK 17，如果老师给的项目是 JDK 8，也要按照项目要求选择对应版本。

四、原因二：src 文件夹没有标记为 Sources Root

普通 Java 项目中，src 文件夹必须被 IDEA 识别为源码目录。如果 src 没有被标记为 Sources Root，IDEA 就可能把它当成普通文件夹处理，里面的 Java 类自然也无法正常识别。

正常情况下，src 文件夹被识别后一般会变成蓝色。如果你看到 src 是普通颜色，或者右键 Java 文件没有运行选项，就要检查 Sources Root。

解决方法：右键 src 文件夹，选择 Mark Directory as -> Sources Root。设置完成后，重新等待 IDEA 索引项目。

图3 将 src 标记为 Sources Root 后，IDEA 才能正确识别源码目录

这个问题在普通 Java 项目中非常常见。特别是老师只发了一个 src 文件夹，或者你从压缩包里直接打开了某个子目录时，很容易出现 src 没有被识别的问题。

五、原因三：Maven 依赖没有下载成功

如果项目中有 pom.xml 文件，说明这是一个 Maven 项目。Maven 项目中的很多类和注解都来自外部依赖，如果依赖没有下载成功，代码就会爆红。

例如 Spring Boot 项目中，如果 spring-boot-starter-web 没有下载成功，@SpringBootApplication、@RestController、SpringApplication 等内容都可能爆红。

解决方法是在 IDEA 右侧 Maven 面板中点击 Reload All Maven Projects，或者右键 pom.xml，选择 Maven -> Reload Project。然后等待依赖下载完成。

图4 Maven 依赖没有加载成功时，pom.xml 和相关类容易爆红

如果刷新后仍然爆红，可以检查网络是否正常、Maven 仓库是否配置正确、本地仓库中是否有下载失败的依赖。遇到 Dependency not found、Plugin not found、Could not find artifact 这类提示时，大多数都和依赖下载有关。

六、原因四：导入项目时打开了错误的文件夹

很多初学者导入项目后代码爆红，是因为打开的文件夹不对。比如一个完整项目叫 JavaProject，里面有 src、pom.xml、README.md 等文件，但你只打开了 src 文件夹。这样 IDEA 可能无法识别完整项目结构。

普通 Java 项目一般要打开包含 src 的最外层项目目录；Maven 项目一般要打开包含 pom.xml 的目录。如果打开的目录太深，项目配置就容易丢失。

图5 打开项目根目录和只打开 src 文件夹的区别

判断是否打开正确目录，可以看左侧 Project 面板中是否能看到完整结构。如果是 Maven 项目，左侧应该能看到 pom.xml；如果是普通 Java 项目，应该能看到 src 所在的项目根目录。

七、原因五：JDK 版本和项目要求不一致

有时候项目不是没有 JDK，而是 JDK 版本不对。例如项目要求 JDK 17，但你配置的是 JDK 8，就可能出现代码爆红或编译失败。

常见报错包括 java: 错误: 不支持发行版本 17、Unsupported class file major version、class file has wrong version 等。这类错误通常说明当前 JDK 版本和项目要求不一致。

图6 JDK 版本不匹配时，编译输出中常见的报错提示

解决方法是检查三个位置：Project SDK、Language level、Maven Runner 的 JRE。如果 pom.xml 中写的是 java.version 17，那么 IDEA 项目 SDK 和 Maven 运行环境也尽量保持 JDK 17。

八、原因六：包名和导入路径错误

如果只有某几个类爆红，而不是整个项目爆红，就要检查包名、类名和 import 是否正确。Java 中 package 声明应该和文件夹路径对应，import 的类也必须真实存在。

比如代码中写了 import com.demo.utils.StringUtil，但是项目中根本没有这个类，或者这个类实际在其他包路径下，就会出现 package does not exist 或 Cannot resolve symbol。

图7 import 路径错误或类不存在时，IDEA 会提示 Cannot resolve symbol

解决这类问题时，可以按住 Ctrl 点击类名，看 IDEA 能否跳转到对应类。如果无法跳转，说明这个类没有被当前项目识别。此时需要检查类是否存在、包名是否正确、依赖是否引入。

图8 package 声明和文件路径不一致也会导致代码爆红

九、原因七：第三方 jar 包或本地 lib 没有导入

有些老项目不是 Maven 项目，而是把第三方 jar 包放在 lib 文件夹中。如果导入项目时这些 jar 包没有被 IDEA 加入依赖，项目中的相关类也会爆红。

常见表现是某些工具类、数据库驱动、第三方 API 无法识别。解决方法是在 Project Structure -> Modules -> Dependencies 中添加对应 jar 包，或者把项目改成 Maven 方式管理依赖。

如果你看到项目中有 lib 文件夹，但里面的 jar 包没有被识别，可以右键 jar 包选择 Add as Library，或者在 Project Structure 中手动添加。

十、原因八：IDEA 缓存或索引异常

有时候 JDK 配置正确，Maven 依赖也下载完成了，src 也标记好了，但 IDEA 仍然显示爆红。这种情况可能是 IDEA 缓存或索引出了问题。

可以尝试点击 File -> Invalidate Caches / Restart，然后选择 Invalidate and Restart。IDEA 会重启并重新索引项目。

图9 清理 IDEA 缓存适合放在最后一步处理

需要注意的是，清理缓存不是万能方法。建议先检查 JDK、src、Maven 和项目目录，确认这些都没问题后，再进行缓存清理。否则只是重启 IDEA，真正的问题仍然存在。

十一、原因九：IDEA 没有重新索引或项目还在加载中

新导入项目时，IDEA 需要一段时间建立索引，Maven 也需要下载依赖。如果项目刚打开就看到爆红，可以先看右下角是否显示 Indexing、Downloading 或 Resolving dependencies。

如果 IDEA 正在索引，不建议马上关闭软件或反复修改配置。等待索引完成后，很多红色提示会自动消失。尤其是第一次打开大型项目时，这个过程可能会比较久。

如果等待后仍然爆红，再按照前面的步骤继续排查。

十二、IDEA 代码爆红的推荐排查顺序

遇到代码爆红时，建议不要随便乱改文件，而是按照固定顺序排查。这样可以避免越改越乱。

图10 IDEA 中 Java 项目代码爆红推荐排查流程图

简单来说，如果是整个项目大面积爆红，优先检查 JDK、项目根目录、src 和 Maven。如果只是少数类爆红，再检查包名、import、类名和第三方依赖。最后再考虑清理缓存。

十三、常见报错和解决方法对照表

报错或现象	常见原因	解决方法
Cannot resolve symbol	依赖没加载、类不存在、包名错误	刷新 Maven，检查 import 和类路径
package xxx does not exist	包路径错误或依赖缺失	检查 package、目录结构和依赖
No SDK / Project SDK is not defined	JDK 没有配置	设置 Project SDK
src 文件夹不是蓝色	源码目录没有识别	Mark Directory as -> Sources Root
pom.xml 爆红	Maven 依赖或配置错误	Reload Maven，检查 pom.xml
Unsupported class file major version	JDK 版本不匹配	更换正确 JDK 版本
class file has wrong version	编译版本和运行版本不一致	检查 Project SDK 和 Maven Runner
注解全部爆红	框架依赖没有下载成功	刷新 Maven 或检查网络
运行按钮消失	没有 main 方法或源码目录未识别	检查 main 方法和 Sources Root
清缓存后仍爆红	根本原因未解决	重新检查 JDK、Maven 和项目结构

十四、总结

IDEA 中 Java 项目代码爆红并不一定代表代码写错。对于初学者来说，大多数大面积爆红都和环境配置有关，尤其是 JDK、src、Maven 和项目目录。

如果遇到爆红问题，可以先按照下面思路排查：第一，看项目是不是完整打开；第二，看 JDK 是否配置；第三，看 src 是否被识别为源码目录；第四，看 Maven 依赖是否加载；第五，看包名和 import 是否正确；最后再清理 IDEA 缓存。

只要掌握这个排查顺序，遇到 IDEA 代码爆红时就不会再盲目乱改代码。对于 Java 初学者来说，学会分析错误来源，比单纯记住某一个解决方法更重要。