ThinkPHP 5.0 模板注释仅在模板编译阶段生效并被剔除，不输出到HTML、不被PHP解析；书写须紧贴{无空格，禁用嵌套与未转义{}；缓存未清会导致“注释失效”假象；不可替代PHPDoc或业务文档。
ThinkPHP 5.0 模板注释本身语法简单，但在旧项目长期维护中容易因忽略细节引发误解、调试困难或缓存残留问题。关键不在“会不会写”，而在于“什么时候生效”和“谁会看到它”。
模板注释只在模板层生效，不进入 PHP 执行流程
模板注释（{/* 注释内容 */} 或 {// 注释内容}）由 ThinkPHP 模板引擎在编译阶段识别并剔除，**不会出现在最终输出的 HTML 中，也不会被 PHP 解析器读取**。这意味着：
- 它对控制器、模型、配置等 PHP 文件完全无效——那些地方必须用
//或/* */ - 不能用来临时禁用一段逻辑（比如
{/* {if $a}...{/if} */}），因为嵌套标签会导致编译失败或静默跳过 - 注释里不能包含未转义的
{或}，否则会破坏模板解析器的状态机，常见于复制粘贴 JSON 或 JS 代码片段时
注释格式有硬性空格限制
ThinkPHP 5.0 对模板注释的书写格式敏感：
-
{// 和 {/* 必须紧贴左大括号
{，中间**不能有任何空格**；写成{ //或{ /*将被当作普通文本输出 - 注释结尾的
*/}或//}同样不能有多余空格，尤其注意 Windows 编辑器可能自动插入不可见字符 - 多行注释支持换行，但每行开头仍需保持
{/*连续，不可拆成两行写
开发与生产环境差异易导致“注释失效”假象
看似注释没起作用，实际常是缓存机制干扰：
立即学习“PHP免费学习笔记（深入）”；
- 模板注释在编译后即被删除，但编译产物（如
Runtime/Cache/Home/xxx.tpl.php）会缓存。删了源模板文件里的注释，若没清空Runtime/Cache和Runtime/Temp，旧编译结果仍运行 - 调试模式（
app_debug = true）下模板每次都会重新编译；关闭后则强依赖缓存。旧项目上线后关了调试却忘了清缓存，就会出现“改了注释但页面还是老样子” - 某些 IDE 或编辑器插件会误将模板注释高亮为 PHP 注释，造成视觉混淆，需确认语法定义是否匹配 TP5.0 模板规则
别把模板注释当文档或协作工具用
模板注释适合标注局部逻辑意图（如 {// 这里要兼容 IE11 的 flex 布局降级}），但不适合承载结构说明：
- 它不会被任何文档生成工具（phpDocumentor、Swagger）识别，也不参与类型推导或 IDE 跳转
- 团队交接时，重要业务规则、字段含义、接口约定应写在控制器方法的 PHPDoc 里，而非藏在模板注释中
- 如果模板里大量依赖注释解释变量来源（如
{// $user 来自 UserController::index() 的 assign()}），说明 PHP 层数据传递已不够清晰，应优先重构逻辑而非补注释
