PhpStorm 新建 PHP 类命名空间为空、接口语法错误、PHPDoc 失效，主因是模板配置错误：未正确设置 $NAMESPACE$、未标记源码根目录、未区分 interface/trait 模板、PHPDoc 位置或格式错误，且必须重启 IDE 刷新缓存。
新建 PHP 类不带命名空间、没 PHPDoc、接口写成 class ——不是 PhpStorm 抽风，是模板根本没配对。
PHP Class 模板里 $NAMESPACE$ 为空或不替换
这是最常卡住的点：你写了 namespace ${NAMESPACE}，生成文件里却空着，或者直接显示文字 ${NAMESPACE}。
- 必须保留第一行
#parse("PHP File Header.php")，否则${NAMESPACE}永远为空；这个 include 是 PhpStorm 解析命名空间的唯一入口 -
PHP File Header.php要在 Includes 标签下存在（哪怕内容为空），不能只在 Files 下有 PHP Class 模板 - 项目根目录下对应源码路径（比如
src/）必须右键 → Mark Directory as → Sources Root，否则 IDE 不知道从哪推导命名空间 - 改完模板后不重启 PhpStorm，缓存会继续输出原始变量名，比如
$DATE$不变日期、$NAME$不替换成类名
Interface / Trait 新建后语法错误（class UserServiceInterface）
默认 PHP Class 模板不区分语言结构，interface 和 trait 全套复用 class 模板，结果生成非法语法。
- 去
File and Code Templates → Files，复制一份PHP Class，重命名为PHP Interface - 把
class ${NAME}改成interface ${NAME}，删掉extends \Exception、implements等类专属内容 - 同理新建
PHP Trait模板，只留trait ${NAME}，别加extends或implements -
${NAME}可用，但${CLASS_NAME}是弃用变量，别用
PHPDoc 块换行错乱或不生效
你加了 /** @package ${NAMESPACE} */，结果注释贴在 class 同一行，或者生成后多出空行、缩进崩坏。
立即学习“PHP免费学习笔记（深入）”；
- 必须用块级写法
/**开头 + 换行 +*+ 换行 +*/结尾，别写成单行/** @package ... */ - PHPDoc 要放在
namespace声明之后、class声明之前，顺序错就可能被 IDE 当作普通注释处理 - 如果用了
#parse("xxx")引入其他模板，被引入的文件也得在 Files 分类下（不是 Includes），否则变量不传递 -
@inheritdoc不会自动加到接口方法文档里，得手动补进PHP Interface模板的 PHPDoc 中
JS/TS 文件模板里 ${DATE} 格式固定，想改 YYYY-MM-DD 怎么办
${DATE} 在 PhpStorm 里硬编码为 YYYY/MM/DD，没法通过变量配置改；${YEAR}-${MONTH}-${DAY} 这种写法也不支持。
- 可用组合：用
${YEAR}-${MONTH}-${DAY}+${HOUR}:${MINUTE}，它们是独立变量，能拼出2026-04-10 22:59 -
${TIME}格式取决于系统设置，不稳定，建议避开，优先用${HOUR}和${MINUTE} - 所有时间类变量（
${DATE}、${YEAR}等）只在 Files 类型模板中有效，Includes 或 Live Templates 里不解析 - 如果需要更灵活的时间格式（如带秒、时区），得靠外部脚本 + 文件监听，模板层做不到
真正卡住人的从来不是“怎么加一行注释”，而是变量不展开、命名空间取不到、模板类型选错这三件事。改完记得关掉 PhpStorm 再打开——IDE 的模板缓存比你想象中顽固得多。
