# IntelliJ IDEA 2025.3 启动卡死问题解决记录：只有打开 Java 项目才会卡在进度条
最近遇到一个奇怪的问题：IntelliJ IDEA（版本 2025.3）启动时只要打开 Java 项目，就会卡在进度条界面（显示 "Indexing..." 或类似进度叠加层），整个界面无响应，需要强制退出。而打开前端项目（Vue/React/JS 等）却完全正常。
经过多天排查（thread dump、日志、storage diagnostic 等），终于定位并解决。记录如下，供大家参考。
## 问题现象
- IDEA 启动后自动打开上一个 Java 项目 → 进度条卡住 → "IntelliJ IDEA is not responding"。
- 强制退出后重新启动，不打开任何项目（停在 Welcome 界面）→ 正常。
- 手动打开前端项目 → 正常。
- 手动打开 Java 项目 → 再次卡死。
- 堆内存已调到 `-Xmx2048m`（甚至更高），无效。
- Invalidate Caches 多次尝试，偶尔能进，但下次打开 Java 项目又卡。
## 排查过程
1. **采集 thread dump**（使用 jstack 或 Activity Monitor）
发现主线程（AWT-EventQueue-0）卡在 `SuvorovProgress.dispatchEventsUntilComputationCompletes`，正在等待后台任务完成。
2. **关键堆栈**
后台任务卡在结束 **dumb mode**（索引模式）：
DumbServiceImpl.decrementDumbCounter
→ runWriteAction
→ upgradeWritePermit (NestedLocksThreadingSupport)
同时有 **多个协程**（通常 7 个）悬挂在：
ReaderModeSettingsCompanionapplyReaderMode$1.invokeSuspend
→ InternalReadAction.readLoop
3. **其他诊断文件**
- `storage-diagnostic.json`：索引数据很小，共享索引（shared indexes）正常加载。
- `idea.log`：无明显 ERROR。
- 确认只有 Java 项目触发，前端项目不触发 → 指向 Java 库源码相关的功能。
## 根源分析
核心原因是 **Reader Mode（阅读模式）** 在 dumb mode 结束时尝试对库源码（JDK、Maven/Gradle 依赖的 decompiled sources）应用渲染设置，导致后台任务阻塞，进而阻塞读/写锁升级，最终 UI 永久卡在进度条。
- Reader Mode 是 IDEA 2023+ 引入的功能，主要用于优化阅读**只读文件/库源码**的体验（隐藏行号、加大行距、突出 JavaDoc 等）。
- Java 项目会自动加载大量库源码，而 Reader Mode 在索引刚完成时尝试渲染这些文件（尤其是 JavaDoc 较多的类），容易在 read action 中悬挂。
- JetBrains 平台在 2025.x 版本中对写操作锁机制进行了优化（后台协程更多），但仍存在不稳定情况，官方博客和 YouTrack（如 IDEA-266217）有类似 UI freeze 报告。
**注意**：手动修改 Maven 仓库中的 jar（解压查看等）不是主要原因，顶多是次要诱因（权限或来源不一致可能加剧渲染问题），但关闭 Reader Mode 后即使不恢复 jar 也能正常。
## 解决方案（已验证有效）
### 方法一：在设置中关闭 Reader Mode（推荐，能进 Welcome 界面即可操作）
1. 启动 IDEA，停在 Welcome 界面（不要打开项目）。
2. 点击右上角 **Configure → Settings**（或 `Cmd + ,`）。
3. 搜索 “Reader Mode”。
4. 进入 **Editor → Reader Mode**。
5. 将所有选项关闭：
- 主开关 **Enable Reader Mode**
- **Show in lightweight mode**
- 其他相关选项
6. Apply → OK → 重启。
### 方法二：手动编辑配置文件（完全无法进设置时使用）
路径：`~/Library/Application Support/JetBrains/IntelliJIdea2025.3/options/`
新建或编辑 `reader.mode.xml`：
```xml
<application>
<component name="ReaderModeSettings">
<option name="enabled" value="false" />
<option name="showInLightweightMode" value="false" />
<option name="applyToReadOnlyFiles" value="false" />
</component>
</application>
预防建议
- Java 项目较大时，建议默认关闭 Reader Mode（除非你经常阅读库源码）。
- 如需查看 jar 内容，优先使用 IDEA 自带反编译或 attach 官方 sources jar，不要手动解压修改 Maven 仓库。
- 定期 Invalidate Caches，保持索引干净。
- 关注 IDEA 更新，2025.3 后续 patch 可能进一步修复类似 freeze。
总结
这个问题非常隐蔽，表面看像是索引卡顿或内存不足，实际是 Reader Mode + 平台锁机制不稳定 导致的后台任务阻塞。只影响 Java 项目是因为它大量触发库源码渲染。
简单关闭 Reader Mode 即可彻底解决，无需重装 IDEA 或删除所有配置。
希望这篇记录能帮到遇到同样问题的朋友！