PHP属性注释必须使用标准PHPDoc的@var标签，紧贴属性上方，类型需覆盖所有可能值，即使PHP 8.4+支持原生类型声明，仍需保留@var以确保IDE和静态分析工具正常工作。

PHP 属性注释不是可选操作，而是类型推导、IDE 跳转、静态分析（如 PHPStan / Psalm）和 PHP 8.0+ 原生属性类型声明协同工作的基础。没写对注释，@var 就形同虚设。

PHP 属性注释必须用 @var，不能用 // 或 /* */

PHP 解析器本身不读取属性上方的普通注释，只有 PHPDoc 标准的 @var 才会被 IDE 和静态分析工具识别。写成这样完全无效：

/** 这个注释不会被识别为类型 */
private $items;
// 这个也完全没用
private $count = 0;

正确写法必须是标准 PHPDoc 块，紧贴属性声明上方，且含 @var 标签：

/**
 * @var array
 */
private $scores;
/**
立即学习“PHP免费学习笔记（深入）”；

							

								
								

									Smart Picture
									
Smart Picture 智能高效的图片处理工具
								
								下载 
							
						
@var User|null
*/
public $owner;

注意：@var 后面**不能有属性名**（比如 @var User $owner 是旧式写法，PHPStan 从 1.5+ 开始已弃用，现代工具普遍不支持）。

@var 类型写法要匹配实际使用场景

类型不是越“精确”越好，而是要覆盖所有可能值。常见误写包括：

• 写死非空类型，但属性可能为 null（如未初始化或可被重置）
• 用 array 而不用泛型语法，导致 IDE 无法提示键/值类型
• 忽略联合类型（PHP 8.0+ 支持 |，PHPDoc 也支持）

推荐写法示例：

/**
 * @var string|null  // 明确允许 null
 */
private $name;
/**
立即学习“PHP免费学习笔记（深入）”；
@var list  // 表示索引数组，比 array 更准确
*/
private $ids;
/**
立即学习“PHP免费学习笔记（深入）”；
@var Resource|string  // 联合类型，兼容不同返回路径
*/
private $handle;

PHP 8.4+ 属性 PHPDoc 可省略？不，仍需保留

PHP 8.4 引入了原生属性 PHPDoc（RFC: Property PHPDoc），允许在属性声明中直接写类型注释，例如：

private User $owner; // PHP 8.4+ 原生支持，等价于 @var User

但请注意：这仅适用于**有原生类型声明的属性**；没有类型声明的属性（如 private $data;）依然必须靠 @var 注释；而且主流静态分析工具（PHPStan、Psalm）当前版本（2024 年中）尚未完全适配该语法，仍强烈依赖传统 @var。

所以目前最稳妥的做法仍是：所有属性，无论是否带原生类型，都补上完整 @var 注释。

IDE 不识别 @var？检查这三处

写了注释但 PHPStorm / VS Code（with Intelephense）没提示，大概率是以下原因：

• PHPDoc 块没有**紧贴属性上方**（中间不能有空行或别的语句）
• 用了错误标签，比如写成 @param、@return 或漏掉 @
• 项目根目录缺少 phpstan.neon 或 psalm.xml 配置，导致类型推导未启用

特别注意：VS Code 的 Intelephense 默认只扫描打开的文件。如果属性在未打开的类里，注释再规范也不会触发提示——这是缓存机制，不是写错了。

真正麻烦的不是怎么写 @var，而是团队里有人改了属性逻辑（比如把 string 改成可为 null），却忘了同步更新 @var 注释。这种不一致会悄悄绕过所有类型检查，直到运行时报错。

https://www.php.cn/faq/1990106.html