必须配置php解释器、启用psalm插件、规范使用@template等注解，三者缺一不可；否则数组形状、泛型、@var补全均失效。
PhpStorm 默认就开启基础类型推断，但要真正用上 数组形状、@template 泛型、@var 注解补全等高级能力，必须手动配齐三样东西：PHP 解释器、Psalm 插件、类型注解习惯。
为什么写了 @var 还没补全？先检查 PHP 解释器是否生效
没有解释器，PhpStorm 就是“睁眼瞎”——它连 array 是什么、DateTime 有哪些方法都不知道。类型推断不是纯静态猜的，它严重依赖解释器提供的函数签名和类结构。
- 进
File → Settings → Languages & Frameworks → PHP，确认CLI Interpreter已指向真实 PHP 可执行文件（如/usr/bin/php或C:\xampp\php\php.exe） - 点开解释器右侧的
…，看“Loaded extensions”里有没有json、mbstring等常见扩展；若为空或报错，说明路径不对或 PHP 损坏 - 新建一个
test.php，写<?php $d = new DateTime(); $d->，按Ctrl + Space—— 如果没弹出方法列表，解释器就没通
数组键名/对象属性补全不工作？Psalm 插件可能被关了
PhpStorm 对 array<string user></string> 或 #[ObjectShape] 的支持，底层靠的是 Psalm 插件。它虽默认捆绑，但可能被手动禁用，或在旧项目中未激活。
- 打开
Settings → Plugins，搜索Psalm，确保PHP Psalm Language Support已勾选并启用 - 重启 PhpStorm（插件启用后必须重启才生效）
- 验证方式：新建文件写
/** @var array{foo: string, bar: int} $data */ $data = [];，然后输入$data['，看是否自动提示foo和bar - 如果仍不提示，右键项目根目录 →
Reload project from composer.json，强制刷新类型索引
泛型类、模板类没类型提示？得用 @template + 正确 PHPDoc 格式
泛型不是写个 class Collection 就能推断的，必须配合 Psalm 风格注解，且注解位置不能错。
立即学习“PHP免费学习笔记（深入）”；
-
@template必须写在类声明上方的 PHPDoc 块里，不能放在构造函数或方法里 - 参数和返回值要用
@param/@return显式绑定模板变量，例如：/** @template T */ class Box { /** @var T */ private $value; <pre class='brush:php;toolbar:false;'>/** @param T $value */ public function __construct($value) { $this->value = $value; } /** @return T */ public function get() { return $this->value; }}
- 调用时，PhpStorm 才会根据实例化传入的类型（如
new Box('hello')）把get()返回值识别为string - 注意：PHP 8.2+ 原生支持
class Box<t></t>语法，但 PhpStorm 当前（2026 年初）仍更稳定兼容 Psalm 注解风格
补全时总提示 “Plain Text” 或 “Unknown class”？文件类型和命名空间常被忽略
类型推断链条很脆弱：文件没被识别为 PHP、类没正确声明命名空间、vendor 没索引——任一环节断掉，补全就失效。
- 右下角状态栏看到
Plain Text？立刻右键编辑器标签页 →Override File Type → PHP - 确认
.php后缀已注册到 PHP 类型：进入Settings → Editor → File Types，查PHP类型下的Registered Patterns是否含*.php - 使用 Composer 依赖时，确保
vendor/目录未被排除（右键 →Mark Directory as → Not Excluded），否则Illuminate\Http\Request这类类名永远标红 - 新建文件别用
Empty File，一定要选PHP File，否则 IDE 不自动加<?php和命名空间模板
最常被跳过的其实是“重启 + 重建索引”：改完解释器或插件后，仅靠 Invalidate Caches and Restart 不够，有时得额外执行 File → Reload project from disk，让 PhpStorm 重新扫描所有 .php 文件和注解结构。
