TP5.1升级后模板标签失效，首要原因是缓存残留，须同时清理runtime/Cache和runtime/Temp目录；其次需严格校验{if}/{/if}闭合、{volist}属性名大小写敏感（仅支持key/id）、嵌套name不冲突，并替换已弃用语法如HTML注释包裹标签、{php}标签及{present}/{empty}旧参数格式。
TP5.1 升级后模板中原本能正常渲染的{volist}、{include}、{empty}等标签突然失效，页面空白或报错“Tag not closed”，不是代码写错了，而是旧模板语法与新版编译器解析规则冲突导致的。
清理 runtime 缓存是第一优先动作
升级后所有模板相关异常，90% 由缓存残留引发。TP5.1 的模板编译缓存分两层：Runtime/Cache 下的 PHP 编译文件 + Runtime/Temp 下的哈希映射表。只删 Cache 目录等于没清。
进入项目根目录 → 打开 terminal → 执行：rm -rf runtime/Cache/* runtime/Temp/*
Windows 用户请用资源管理器手动删除 runtime/Cache 和 runtime/Temp 两个文件夹下的全部内容，不要只删子文件夹，必须清空到最底层。
这一步操作起来很简单，直接把 runtime 下这两个文件夹拖进回收站就行。但漏掉 Temp 目录会导致框架仍加载损坏的缓存映射，后续所有修复都白做。
检查标签闭合与嵌套合法性
TP5.1 模板引擎对标签配对更严格，尤其在嵌套场景下容易静默失败。先定位最近修改过的模板文件，重点排查三类结构：
方法一：{if} / {/if} 成对校验
打开出问题的 .html 模板 → 按 Ctrl+F 搜索 {if → 确认每个 {if 开头都有对应 {/if}，且中间未混入未转义的 { 或 } 字符。比如 {if $a > 0} {/if} 合法，但 {if $a > 0 && $b{0}} 会中断解析——因为 $b{0} 是 PHP 7.4+ 已弃用语法，引擎会卡在 { 处。
方法二：{volist} 属性名大小写敏感
{volist name="list" key="k"} 正确；{volist name="list" KEY="k"} 或 {volist name="list" index="k"} 都会静默跳过整个块，不报错也不输出。ThinkPHP 5.1 只识别 【key】 和 【id】 两个属性名，其余如 index、i、k 都无效。
方法三：嵌套循环命名冲突
外层 {volist name="users"} → 内层不能写 {volist name="users"}，否则内层变量覆盖外层，最终只渲染最后一组数据。必须改用 {volist name="users.children"} 或 {volist name="sublist"}。
替换已弃用的模板语法
TP5.1 不再支持以下写法，必须人工替换：
① 删除所有 和 行内注释。这类 PHP 注释若位于标签内（如 {foreach $list as $v}{$v.name}{/foreach}），会触发解析中断，导致后续标签不闭合。
② 将 HTML 注释包裹的模板代码改为条件标签：
错误写法：<!-- {extend name="base"} -->
正确写法：【{extend name="base" /}】（必须独立成行，不加任何 HTML 注释包裹）
③ 禁用 {php} 标签：
{php}echo 'test';{/php} 在 TP5.1 中默认被拦截（tpl_deny_php => true），应改为 {$think.const.TEST} 或使用函数调用 {$var|md5}。
④ 替换 {present} / {empty} 的旧参数格式：
旧写法 {present name="user.name"} → 新写法 {present name="user.name"}（name 属性值必须带点号层级，不能写成 {present name="user"}）。
验证自定义标签注册时机
自定义标签必须在模板引擎初始化前注册，否则编译阶段无法识别。
第一步：确认注册位置是否在 app/common.php 或 app/provider.php 中，而非控制器或中间件里。
第二步：检查类路径是否可自动加载，运行 php think optimize:autoload 测试自动加载是否生效。
第三步：自定义标签类必须继承 \think\template\TagLib，且 parseTag 方法返回数组结构，不能返回字符串或 null。
常见错误是标签名用了 if、php、include 等关键词，会被内置解析器提前截断，导致整个标签块被忽略。
