$NAMESPACE$ 需三重确认才生效：标记Sources Root、目录结构匹配PSR-4、模板首行含#parse("PHP File Header.php")；缺一不可，且修改后必须重启PhpStorm。
$NAMESPACE$ 不是“填进去就生效”的变量，它依赖三重确认才能展开为真实包名（即 PSR-4 命名空间路径）。
为什么 $NAMESPACE$ 总是空或显示为文字
根本原因不是模板写错了，而是 PhpStorm 没法推导命名空间来源。它只在一种情况下生成 $NAMESPACE$：当前文件将被保存到一个标记为 Sources Root 的目录下，且该目录结构与命名空间一一对应（如 src/Http/Controllers → AppHttpControllers）。
- 没标记 Sources Root：右键项目中实际存放类的目录（如
src），选 Mark Directory as → Sources Root - 标记了但路径不匹配：比如目录是
app/Models，却期望生成AppModels，就得确保app是 Sources Root，且composer.json中 PSR-4 映射正确（"App\": "app/"） - 模板里漏了
#parse("PHP File Header.php")：这个指令必须出现在 PHP Class / Interface / Trait 模板最开头，否则$NAMESPACE$解析链中断，值为空 -
PHP File Header.php必须存在于 Includes 标签下（Settings → Editor → File and Code Templates → Includes），哪怕内容为空
PHP File 和 PHP Class 模板里的 $NAMESPACE$ 行为差异
PHP File 模板用于新建空白 .php 文件（如控制器、命令行脚本），$NAMESPACE$ 仅当该文件将被存入 Sources Root 下的子目录时才有效；而 PHP Class 模板专用于类定义，会强制把 $NAMESPACE$ 插入 namespace 声明行——但前提是上述条件全部满足。
- 在
PHP File模板中写namespace ${NAMESPACE};，如果文件最终保存在非 Sources Root 目录（如public/），${NAMESPACE}就是空字符串，结果变成namespace ;，语法错误 - 在
PHP Class模板中，推荐写法是：/** * @package ${NAMESPACE} */ #parse("PHP File Header.php") class ${NAME} {——注意#parse必须紧接在注释之后、class之前，且不能换行错位 -
${NAMESPACE}中的斜杠是反斜杠，不是正斜杠/，别手动改成App/Http/Controller
改完模板不生效？重启是硬性要求
PhpStorm 对文件模板有强缓存机制。修改任意一处（包括 PHP File Header.php 内容、Sources Root 标记、模板变量写法），都必须完整退出 IDE 再启动，否则你看到的仍是旧行为：$NAMESPACE$ 不替换、$DATE$ 停在 2026-01-01、$NAME$ 留着原样。
立即学习“PHP免费学习笔记（深入）”；
- 验证是否生效：新建一个类，看生成文件里
namespace行是否正确，以及 PHPDoc 中@package后是否跟上完整命名空间 - 常见假成功：模板里写了
namespace AppHttpControllers;这种硬编码——这不是自动填充，是静态文本，和$NAMESPACE$无关 - 如果用了
#parse("xxx")引入其他模板，被引入的文件也必须在 Files 分类下（不是 Includes），否则变量无法传递
真正卡住人的地方，往往不是变量名写错，而是 Sources Root 没标对、#parse 被删了、或者改完没重启——这三个点漏掉任何一个，$NAMESPACE$ 就永远是空的。
