必须选“Invalidate and Restart”才真正生效，因仅Invalidate只标记缓存失效而不释放JVM内存中的符号索引、类型推断上下文及插件元数据，标红、跳转失效等问题持续存在。
只点 Invalidate Caches 不重启，等于没做——所有标红、跳转失效、Ctrl+Click 失灵问题照旧，因为 JVM 内存里的符号索引和类型上下文根本没释放。
为什么 Invalidate Caches 必须配 Restart 才算真清理
PhpStorm 的缓存是内存（JVM 中加载的符号表、VCS 状态、插件元数据）+ 磁盘（system/caches、index 文件）混合结构。Invalidate Caches 操作本身只是“打个失效标记”，不触发内存回收，也不清空已驻留的解析上下文。
- 你刚改完
composer.json或启用了 Laravel Plugin，但类注解仍不解析？那是旧插件元数据还在内存里跑 -
PHP Interpreter路径更新了，但@var提示还是报错？IDE 仍在用旧解释器参与静态分析 - 点了
Invalidate后手动关掉弹窗，或只勾选Clear file system cache就点Cancel？缓存状态完全没变
别一上来就全量重建：先试试 Cache Recovery
如果你只是某几个类突然标红、Find Usages 返回空、新写的 trait 不被识别，且项目含大量 vendor（比如 >5 万文件），Invalidate and Restart 可能要等 5–10 分钟。这时该用更轻量的修复：
- 菜单栏 →
File → Cache Recovery → Repair IDE - 第一步「刷新虚拟文件系统」：立刻解决 NFS 挂载中断、权限突变导致的“文件存在但读不到”假象
- 第二步「重新扫描项目索引」：默认跳过
vendor，只处理修改过的.php和.inc，速度比全量快 3–5 倍 - 第三步「删除共享索引」：仅影响 PhpStorm 2025.1+ 的远程 Composer 包索引服务，本地项目可忽略
vendor/autoload.php 标红？这不是缓存问题，是配置漏了
缓存清得再干净，vendor/autoload.php 如果没被 PhpStorm 当作自动加载入口，第三方类和自定义包照样标红。
立即学习“PHP免费学习笔记（深入）”；
- 右键
vendor目录 →Mark Directory as → Excluded（避免扫描拖慢索引） - 再右键
vendor/autoload.php→Mark as PHP Include Root（明确告诉 IDE 这是加载起点） - 进
Settings → Languages & Frameworks → PHP → Composer，确认勾选Enable composer library detection，且composer.json路径指向项目根目录 - 如果刚改过 PSR-4 映射，记得运行
composer dump-autoload -o，否则 IDE 读不到新规则
手动删缓存目录前必须核对三件事
直接删 ~/.PhpStorm2025.3 或 ~/.cache/JetBrains/PhpStorm2025.3 确实快，但也最容易误伤：
- 确认路径中的版本号完全匹配——是
~/.PhpStorm2025.3，不是~/.PhpStorm2025.3.1或~/.PhpStorm2025.x；错删会导致下次启动重建全部配置，断点、运行配置、快捷键映射全丢 - 确保
phpstorm64.exe（Windows）或jetbrains-phpstorm（macOS/Linux）进程已退出，否则文件被锁住删不掉 - 是否备份了
~/.PhpStorm2025.3/config/options/下的关键文件？比如keymap.xml、colors.scheme.xml——这些不随Invalidate重置，但删整个config就没了
真正卡住索引或持续报错时，最常被忽略的是 vendor 目录既没被 Excluded，也没把 autoload.php 设为 Include Root；缓存清得再勤，这个配置不补上，问题永远在原地打转。
