invalidate caches / restart 是唯一推荐方式，因其按序停用服务、安全清缓存、清本地历史、重置vcs索引并重建符号表；手动删缓存目录易致启动失败、language service不可用及断点残留。
为什么 Invalidate Caches / Restart 是唯一推荐的清理方式
手动删 ~/Library/Caches/JetBrains/WebStorm2025.3 或 %LOCALAPPDATA%\JetBrains\WebStorm2025.3 目录，看似干净彻底，实则高风险。WebStorm 的缓存不是简单文件堆砌，而是包含未完成写入的索引片段、语言服务会话锁、本地历史快照等状态数据。直接删除可能触发三类问题：IDE 启动失败（尤其在 macOS 上常见）、插件报 Language service is not available（Vue/TS 插件最敏感）、断点/折叠状态残留但搜索结果陈旧（因为 .idea/workspace.xml 里还存着旧视图状态，却没了对应缓存支撑）。
官方设计的 Invalidate Caches / Restart 流程会按顺序：停用所有服务 → 安全清空缓存目录 → 清理本地历史 → 重置 VCS 索引 → 重建符号表。它不跳步，也不假设你已退出所有项目。
操作路径：
- macOS：
WebStorm → Invalidate Caches / Restart… - Windows/Linux：
File → Invalidate Caches / Restart…
必须勾选的三项缓存清理选项
弹出对话框后，这三项不是“可选”，而是按场景强制启用：
-
Clear file system cache and Local History：解决窗口布局错乱、断点失效、全局搜索结果不更新。不勾选等于只擦了表面灰，底层索引污染仍在。 -
Clear VCS Log caches and indexes：当你改过 Git 远程地址、执行过git rebase、或看到Log is not available提示时，必须勾选。否则 IDE 仍从旧提交树里读日志。 -
Delete embedded browser engine cache and cookies：前端调试中遇到登录态丢失、CSS 热更新失效、WebSocket 复用异常，大概率是这个残留导致——它和 Chrome DevTools 的缓存不共享，得单独清。
怎么调 webstorm.vmoptions 才不翻车
默认的 -Xms256m -Xmx512m 只够跑单文件 JS 脚本。大型前端项目（尤其含 node_modules）一开就卡，本质是 JVM 堆内存不够用，频繁 GC 导致 UI 线程卡顿。
修改前先确认物理内存：
- 8GB 机器 →
-Xms1024m -Xmx2048m - 16GB 机器 →
-Xms2048m -Xmx4096m - 32GB+ 且常开多个项目 →
-Xms4096m -Xmx6144m，但-Xmx别超物理内存的 1/3
务必加这一行：-XX:ReservedCodeCacheSize=1024m。TypeScript 语言服务依赖它缓存编译字节码，缺了就会降级为“猜词式补全”。改完必须完全退出 WebStorm（关掉所有窗口 + 检查进程是否消失）再重启，否则参数不加载。
哪些目录必须 Mark as Excluded
WebStorm 默认递归索引整个项目目录。一个 node_modules 平均含 2–5 万文件，全索引不仅拖慢启动，还会污染符号表——比如搜 useState，IDE 先从 React 源码里捞几十个同名定义，再过滤，响应自然慢半拍。
右键标记为 Excluded 的目录包括：
-
node_modules（所有项目都必须） -
dist、build、.next、unpackage、coverage（产出目录，无源码价值） -
.git（除非你重度依赖 IDE 内 Git 图形化操作）
注意：Excluded 图标（灰色文件夹）要出现在整个目录树上，不是只在顶层；如果用了 pnpm 或 Yarn PnP，还要去 Settings → Languages & Frameworks → JavaScript → Libraries 检查是否误把 node_modules 手动加进了库路径——这种配置会让 Exclude 失效。
真正卡住的时候，往往不是缓存没清，而是 node_modules 没 exclude、vmoptions 没调、或者三项清理选项漏勾了一项。这些动作之间有依赖关系，少做一步，效果就打折。
