应取消勾选“Comment at first column”：在Settings/Preferences→Editor→Code Style→PHP→Wrapping and Braces中关闭该选项，使//注释自动对齐当前代码缩进；同时在Code Generation中勾选“Add a space at comment start”确保//后自动加空格。
Comment at first column 被意外勾选导致注释顶格
这是最常见、最直观的注释样式异常：你在 if 块里按 Ctrl + /，结果生成的 // 注释紧贴行首，完全不跟随缩进。根本原因就是 Comment at first column 开关被打开了。
修复路径：Settings/Preferences → Editor → Code Style → PHP → Wrapping and Braces，取消勾选 Comment at first column。该设置对新输入的注释立即生效，无需重启。
- 注意：这个选项在不同语言设置页独立存在——JS 对应
JavaScript → Wrapping and Braces，Python 对应Python → Wrapping and Braces，不能只改 PHP - 如果改完仍无效，检查右下角状态栏是否显示
EditorConfig已启用；若项目根目录存在.editorconfig，它里面的indent_style可能覆盖此设置
新建文件头部注释消失或格式错乱
新建 PHP 文件时没出现作者、日期等头部信息，或内容是 Created by PhpStorm 这种默认文案，说明 PHP File Header 模板被重置或未生效。
恢复路径：Settings/Preferences → Editor → File and Code Templates → Files → PHP File Header。这里必须手动编辑模板内容，例如：
立即学习“PHP免费学习笔记（深入）”；
/**
* @package ${PROJECT_NAME}
* @author ${USER}
* @since ${DATE}
*/关键点：
- 变量必须用
${USER}、${DATE}格式，旧版$USER$写法已失效 - 改完必须点
Apply，仅点OK不保存 - 若文件被标记为
Excluded（右键文件 →Mark as → Excluded），模板将完全不触发
/** 回车后文档注释不展开参数或类型
在函数上方输入 /** 后回车，期望看到 @param 和 @return，结果只输出原始占位符如 ${PARAM_DOC}，说明变量解析链断裂。
这不是模板位置错了，而是机制混淆：文档注释生成依赖两层协同：
-
File and Code Templates → Includes → PHP Function Doc Comment提供基础结构（仅留/** */框架，删掉所有${...}） -
Live Templates → PHP → Abbreviation: /**的模板中填写完整结构，并确保Applicable in: PHP → function declaration且Expand with: Enter
漏掉任一环节，变量都不会被替换。检查时重点看 Live Template 是否启用、作用域是否匹配当前光标位置。
恢复失败时优先排查 EditorConfig 和缓存
即使所有设置都调对了，注释行为仍异常，大概率是外部配置或缓存干扰：
- 关闭
Settings → Editor → Code Style → General → Detect and use existing file indents for editing，否则 PhpStorm 会“尊重”文件里混乱的历史缩进，跳过你的注释规则 - 临时禁用
.editorconfig：重命名项目根目录下的.editorconfig文件，再测试注释行为是否恢复正常 - 清缓存不是万能解，但可排除干扰：
File → Invalidate Caches and Restart → Invalidate and Restart
真正容易被忽略的是：注释样式由三套独立系统控制——快捷键注释（Code Style）、新建文件头（File Templates）、文档注释生成（Live Templates + Includes）。改错其中一层，其他两层看起来正常，问题却始终存在。
