php数组注释只能写在数组声明前或后，用//或/ /说明用途和结构；不能在数组内部写行内注释，否则报语法错误；推荐用phpdoc @var array{key: type}提升ide支持。
PHP 数组注释该用什么语法
PHP 本身不支持在数组字面量内部直接写行内注释（比如 // 或 #），任何在 [...] 里加注释的写法都会导致解析错误。唯一合法且通用的方式是把注释写在数组声明**之前或之后**，用标准的 PHP 注释语法（//、/* */）说明整个数组的用途、结构或关键字段含义。
为什么不能在数组元素间写 // 注释
因为 PHP 解析器在处理数组字面量时，会把 // 后的内容当作代码的一部分尝试解析，而不是跳过——这会导致语法错误或意外截断。例如下面这段会报错：
$config = [
'host' => 'localhost', // 数据库主机
'port' => 3306, // 端口
];实际运行会提示 Parse error: syntax error, unexpected '/'。PHP 7.4+ 虽然支持尾随逗号，但**不支持尾随注释**。
推荐的注释位置和写法
把注释放在数组变量声明上方，用清晰的自然语言说明数组目的；对复杂结构（如多维、键名有业务含义），可配合 /* */ 块注释分段说明：
立即学习“PHP免费学习笔记（深入）”；
- 单行说明用
//，简洁明了 - 结构较复杂时用
/* */，可换行、标注字段语义 - 避免在
=>右侧加注释（不可靠，易被误读） - 如果数组用于函数参数或返回值，优先在函数文档块（
/** @return array */）中描述结构
// 用户权限映射表：key 为角色标识，value 为允许的操作列表
$permissions = [
'admin' => ['create', 'read', 'update', 'delete'],
'editor' => ['create', 'read', 'update'],
'viewer' => ['read'],
];
<p>/*</p><ul><li>API 响应模板结构：</li><li><ul><li>'code': 整数状态码（200/400/500）</li></ul></li><li><ul><li>'message': 提示文本</li></ul></li><li><ul><li>'data': 可选，具体业务数据
*/
$responseTemplate = [
'code' => 200,
'message' => 'success',
'data' => null,
];IDE 和静态分析工具能识别的注释形式
如果你用 PHPStorm、VS Code（配合 intelephense）或 Psalm/PHPStan，可以在数组变量前加 PHPDoc 注释，帮助类型推导和自动补全：
/**
* @var array{
* host: string,
* port: int,
* ssl: bool
* }
*/
$databaseConfig = [
'host' => '127.0.0.1',
'port' => 3306,
'ssl' => false,
];这种 @var array{...} 语法不是 PHP 原生支持，但主流工具能解析并提供准确提示。注意字段名必须与实际键名完全一致（包括大小写和引号），否则类型检查会失效。
最常被忽略的是：数组键名在 PHP 中默认是字符串，但 PHPDoc 的 array{key: type} 里 key 不加引号——这是语法要求，加了反而无法识别。
