Class 'XXX' 标红但运行正常，是 PhpStorm 索引未更新或配置错误所致；需依次执行重载项目、清除缓存、标记 autoload.php 为 Include Root、校准 PSR-4 映射、确认 PHP 解释器与语言级别。

Class 'XXX' 标红但运行正常，先重建索引

这不是代码写错了，是 PhpStorm 的符号索引没跟上文件变化。IDE 没把类文件纳入解析范围，自然找不到定义。别急着改 composer.json 或重命名空间，先让索引重来一遍。

• 按 Ctrl + Shift + O（Windows/Linux）或 Cmd + Shift + O（macOS），触发「Reload project from disk」——强制从磁盘读取当前结构
• 若仍标红，进 File → Invalidate Caches and Restart → Invalidate and Restart：这会清空 .idea/php.xml 和 misc.xml 中的索引元数据，重启后自动重建
• 等右下角提示「Indexing finished」再检查，索引中途看结果毫无意义

vendor/autoload.php 被忽略，得手动“点名”

即使 vendor/autoload.php 存在且项目能跑，PhpStorm 也可能没把它当自动加载入口，导致第三方类和自定义包全标红。

• 右键 vendor 目录 → Mark Directory as → Excluded：避免 IDE 尝试解析全部第三方代码拖慢索引
• 再右键 vendor/autoload.php → Mark as PHP Include Root：明确告诉 IDE 这是自动加载起点
• 更稳妥：进 Settings → Languages & Frameworks → PHP → Composer，勾选 Enable composer library detection，并确认 composer.json 路径指向项目根目录

PSR-4 路径和 namespace 对不上，IDE 推断就失效

运行时靠 vendor/composer/autoload_psr4.php 映射能找对类，但 PhpStorm 静态分析依赖路径与命名空间严格对齐。哪怕只差一个大小写，它就放弃推导。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 检查类顶部的 namespace 声明，比如 namespace AppModels;
• 确认该类文件物理路径是 app/Models/User.php（注意 Models 大写，Linux 服务器区分大小写，IDE 默认也校验）
• 打开 composer.json 的 autoload.psr-4 段，确保映射如 "App\": "app/"：末尾反斜杠、路径斜杠都不能少，也不能多空格
• 改完路径或命名空间后，必须执行 composer dump-autoload -o，再触发一次 Invalidate Caches，否则 IDE 不会读新映射

PHP 解释器或语言级别错位，类型系统直接罢工

用错 PHP 版本或解释器路径，会导致命名空间解析、返回类型提示等底层能力失效，间接表现为类找不到、跳转失败、@var 注解不生效。

立即学习“PHP免费学习笔记（深入）”；

• 进 Settings → Languages & Frameworks → PHP，确认 CLI Interpreter 已正确配置（不是空，也不是指向旧版本 php.exe）
• 检查 Language level 是否匹配代码语法：比如用了 #[Attribute] 却设成 PHP 7.4，类定义就不会被完整解析进索引
• 改完解释器或语言级别后，务必点右上角 Reload project（或 File → Reload project from disk），否则旧索引继续生效

索引重建看着简单，但最容易被跳过的其实是「等索引完成」和「确认 vendor/autoload.php 被标记为 Include Root」这两步。很多人点了 Invalidate 就去写代码，或者忘了排除 vendor 目录，结果索引卡住、变慢、甚至失败。