PHPStorm文档悬浮窗不显示需先启用“Show quick documentation on mouse move”，检查stubs路径、PHPDoc格式及缓存；空白或loading多因stubs未加载或注释不规范；深度查阅推荐Ctrl+Q呼出完整面板。
PHPStorm 文档悬浮窗不显示？先确认是否启用了 Quick Documentation
默认情况下，PHPStorm 的文档预览（即把鼠标悬停在函数、类或方法上时弹出的右侧小窗）是关闭的。它和 Quick Definition（快速跳转定义）不是一回事——后者只显示声明位置，而前者才展示 PHPDoc 或源码注释内容。
启用方式很简单：File → Settings → Editor → General → Other → 勾选 “Show quick documentation on mouse move”。注意下方有个延迟时间（default 500ms），如果设得太短，悬停时容易误触发；太长则响应迟钝，建议保持默认或调到 300–400ms。
- 该设置对 PHP、JavaScript、Python 等语言通用，但文档内容质量取决于你项目里是否有可用的 PHPDoc 或已加载的 stubs
- 如果用的是 Laravel、Symfony 等框架，确保已安装对应插件（如 Laravel Plugin），否则
__construct()或Auth::user()这类动态方法可能没文档 - macOS 用户注意：系统级“辅助功能 → 鼠标键”若开启“悬停点击”，会干扰 PHPStorm 的悬停逻辑，导致文档窗不弹出
为什么悬停后只显示“Loading…” 或空白？检查 PHPDoc 解析路径
PHPStorm 不会自动解析所有注释——它依赖两处来源：当前文件内的 PHPDoc 和 外部 stubs（比如 phpstorm-stubs 或 vendor 中的 docblock）。如果只看到 loading 或空框，大概率是 stubs 没加载或注释格式不标准。
- 检查
Settings → Languages & Frameworks → PHP → Stub Path是否指向了有效的 stub 目录（推荐用官方 phpstorm-stubs，不要用过时的phpstorm-stubs@1.0） - 确认你的 PHPDoc 使用了标准格式，例如：
/** @param string $name */可被识别，但/* @param string $name */（少一个 *）可能被忽略 - 对于 Composer 包中的类，确保
vendor/autoload.php已被 PHPStorm 正确识别（右键项目根目录 → “Load Path from composer.json”） - 执行
File → Invalidate Caches and Restart → Just Restart，缓存损坏常导致文档解析卡在 loading 状态
想让悬浮窗更大、支持滚动、显示继承关系？改用快捷键呼出完整视图
鼠标悬停窗尺寸固定、不支持滚动、也不展示父类方法继承链。真要深度阅读文档，别依赖悬停，改用快捷键：
立即学习“PHP免费学习笔记（深入）”；
-
Ctrl+Q（Windows/Linux）或Ctrl+J（macOS）：呼出可滚动、带语法高亮、含继承/实现信息的完整文档面板 -
Ctrl+Shift+I：内联显示定义 + 文档（比悬停更稳，且支持部分代码补全上下文） - 在文档面板中按
Tab可在“Documentation”、“Hierarchy”、“Usages” 标签间切换，Hierarchy能看到ArrayAccess::offsetGet()是从哪个接口继承来的 - 该面板支持搜索（
Ctrl+F），对长文档特别实用；关闭后下次仍会记住上次打开的标签页
自定义文档渲染效果：禁用 HTML 渲染或调整字体大小
PHPStorm 默认把 PHPDoc 当作 HTML 渲染（支持 <p>、<code> 等标签），但某些老旧注释含未闭合标签会导致排版错乱。另外，文档窗字体默认继承编辑器字号，小屏设备看着吃力。
- 禁用 HTML 解析：进入
Settings → Editor → Color Scheme → General → Code Folding → Show documentation popup as plain text（勾选后，<pre>不再高亮，但避免崩溃） - 单独调大文档字体：在同一页找到
Documentation Popup配色方案，点右侧铅笔图标 → 修改Font大小（建议比编辑器大 2–4px） - 如果文档中大量出现
@link或@see，PHPStorm 会自动加下划线并支持 Ctrl+Click 跳转，这个行为无法关闭，但可放心使用
真正难搞的是跨项目、跨版本的 PHPDoc 一致性——比如本地开发用 PHP 8.2，但生产跑 PHP 7.4，某些 @psalm- 或 @phpstan- 注解会被忽略，文档窗就变空白。这种时候，别调设置，得先统一环境或删掉非标准注解。
