@var注解为PhpStorm提供类型锚点，使Ctrl+B能精准跳转到对应类定义；必须写在变量首次读取前的同一作用域内，且需开启PHP类型推断、语言级别≥7.4、版本匹配才生效。
为什么 @var 注解能影响 Ctrl+B 跳转？
Ctrl+B（或 Cmd+B）本质是「跳转到符号定义」，但 PhpStorm 不会凭空猜类型——它依赖显式锚点。当变量类型模糊（如动态数组、魔术方法返回值、框架容器取值），IDE 无法关联到具体类，跳转就失效或落到 mixed。加 @var 就是人工钉一个类型锚点，让 Ctrl+B 知道该往哪跳。
@var 注解必须写在哪才生效？
位置决定作用域，错位等于白写：
- 必须写在变量首次被读取前的**同一作用域内**（比如函数开头、if 块内、循环体前）
- 不能写在函数外部再期望函数内部生效（PHP 的作用域规则 + PhpStorm 的索引机制双重限制）
- 对类属性，应写在属性声明上方，而非构造函数里赋值时
- 对
$_POST这类超全局，推荐写在控制器方法顶部，紧贴$_POST首次使用前
跳转仍失败？检查这三处配置
注解写了 ≠ 立刻生效，常见卡点：
-
Enable PHP type inference必须开启：Settings → Languages & Frameworks → PHP → 勾选该选项 - 项目 Language level 至少为 PHP 7.4（低于此版本不支持数组形状等现代语法）
- 如果用了
@mixin或@template，确保 PhpStorm 版本 ≥ 2025.2（旧版解析不完整，跳转会断）
数组键名跳转和泛型类怎么处理？
普通 @var User $user 只能跳到 User 类；要让 $data['id'] 中的 id 键可跳转，或让 Collection::make(User::class) 返回值能 Ctrl+B 到 User，得用更细粒度的注解：
立即学习“PHP免费学习笔记（深入）”；
- 数组结构：用
@var array{id: int, name: string} $data，之后点$data['id']的id字符串可跳转到该键定义位置（需 PhpStorm 2026.1+） - 泛型工厂：用
@template T of object+@param class-string<t> $class</t>+@return T，配合@var User $user使用，才能让 Ctrl+B 从变量反推并跳进具体类 -
@mixin对 Laravel 查询构建器有效，但仅限于跳转到 mixin 类的方法，不解决返回值类型跳转问题
类型注解不是“补全开关”，而是给 PhpStorm 提供跳转路径的坐标。写得越准，跳得越稳；漏掉作用域或版本不匹配，就只剩悬停里一行 mixed。
