ThinkPHP模板解析失败主因是标签语法错误：{:xxx()}与{$xxx}混用、{volist}属性名错写、自定义标签未注册或闭合不匹配、缓存未更新。需严格区分变量输出与函数执行，规范属性名，及时清理缓存。
模板中 {:xxx()} 和 {\$xxx} 混用导致解析失败
ThinkPHP 的模板引擎会严格区分变量输出和函数执行，写成 {:func()} 却漏掉冒号，或者把变量 {\$name} 误写成 {:name}，都会直接报“模板解析错误”——不是语法错，而是解析器根本没识别出这是个合法标签。
常见错误现象：Parse error: syntax error, unexpected '{' 或空白页面 + 日志里出现 Template not found（其实是解析中途 abort 了）。
-
{\$var}：只输出变量值，不做任何处理；{:func()}：执行 PHP 表达式或函数，必须带冒号 - 不能写
{func()}（无冒号），也不能写{\$func()}（变量语法不支持调用） - 如果要输出函数返回值，只能用
{:date('Y-m-d')}这类形式；想复用逻辑，建议在控制器 assign 一个变量，再用{\$date_str} - 嵌套函数如
{:md5(\$user['id'])}是允许的，但注意单引号内不能插变量，得用双引号或拼接
使用 {volist} 时 key / name / empty 属性名写错或缺失
{volist} 是高频出错点，属性名必须是英文且大小写敏感，比如写成 {volist name="list" key="i"} 没问题，但写成 {volist name="list" index="i"} 就会静默失败——因为 ThinkPHP 用的是 key，不是 index；漏掉 name 更是直接报解析异常。
使用场景：循环数组、分页数据、关联模型结果集。
立即学习“PHP免费学习笔记（深入）”；
- 必填属性只有
name（传入的变量名），其他如id、key、mod、empty都是可选，但拼错就失效 -
empty必须是字符串，比如empty="暂无数据"，不能写empty={\$empty_tip}（模板里不支持变量赋值给属性） -
key默认是数字索引，如果想用键名（如关联数组的'user_id' => 123），需显式写key="k"，并在循环体里用{\$k} - 嵌套
{volist}时，内层name不能和外层同名，否则会被覆盖，建议加前缀如name="item.children"
自定义标签未注册或闭合不匹配引发解析中断
手动注册了 MyTag，但在模板里写成 {mytag}{/mytag} 却没生效，大概率是闭合标签名大小写不一致（如注册的是 mytag，却写了 {/MyTag}），或者根本没在配置里开启 tpl_taglib_mytag。
性能影响：未注册的标签不会报错，但整段内容被原样输出，后续标签可能因结构错乱而解析失败。
- 自定义标签类名必须是
TagLibXxx（如TagLibMytag），对应配置项为tpl_taglib_mytag - 标签名在模板中全部小写，闭合标签必须与开始标签完全一致，包括顺序和空格（
{mytag}{/mytag}✅，{mytag} {/mytag}❌） - 标签体内不能出现未转义的
{或}，否则解析器提前截断；如有必要，用{:\$str}输出含大括号的字符串 - 调试时可在
think\Template\TagLib的parseTag方法里打日志，确认是否进入解析流程
模板缓存未更新导致旧错误持续复现
改完模板标签后依然报错，甚至删了错误代码还提示“找不到标签”，基本可以确定是缓存没清。ThinkPHP 默认开启模板缓存，生成的 PHP 文件存在 runtime/cache/ 下，解析错误也会被缓存下来。
容易被忽略的地方：开发时关了缓存（'template.cache' => false），但上线又开了，这时候改模板不生效，第一反应常是“是不是语法又错了”，其实只是缓存没刷。
- 最稳妥方式是删整个
runtime/cache/目录，而不是只删某个文件 - 命令行下可用
php think clear:cache --type=template（TP6+）或手动rm -rf runtime/cache/* - 如果用的是 Swoole 或 RoadRunner，还需重启服务进程，否则内存里仍加载着旧缓存
- CI/CD 部署时记得加清理步骤，否则上线后用户看到的还是旧模板解析结果
