模板编译失败主因是语法不合法，需检查标签配对、嵌套规则、缓存清理及调试配置。
模板编译失败：常见错误信息和定位方法
看到 Template compile error 或 Parse error: syntax error, unexpected '{' 这类报错，基本可以确定是模板语法不合法，不是 PHP 本身的问题。ThinkPHP 的模板引擎在编译阶段会把 {volist}、{foreach} 等标签转成 PHP 代码，一旦嵌套错乱或漏写闭合标签，就会卡在编译环节。
关键线索在报错堆栈里带出的临时编译路径，比如：Runtime/Cache/Home/xxx.tpl.php —— 这个文件其实是编译后的 PHP，但出错时它可能根本没生成，或者只生成了一半。真正要查的是原始模板（如 index.html）里最近修改过的那段标签块。
- 优先检查
{if}/{/if}、{volist}/{/volist}是否成对，尤其注意中间是否混入了未转义的{或} - 避免在标签内直接写 PHP 代码，比如
{php}echo $a;{/php}容易破坏解析逻辑，改用{$a}或函数调用 - 如果用了自定义标签，确认其类文件已正确注册，且
parseTag方法返回值结构符合规范
标签嵌套限制：ThinkPHP 5.1+ 对 {switch} 和 {foreach} 的处理差异
ThinkPHP 不支持任意深度嵌套，尤其是 {switch} 内部不能直接写 {volist} —— 它不会报错，但会静默跳过子标签，导致页面渲染为空。本质是标签解析器按行扫描、状态机驱动，遇到未预期的起始标签就丢弃后续内容。
{foreach} 嵌套本身是允许的，但必须严格闭合，且中间不能穿插未识别的标签（比如手误写的 {header}）。5.1 后版本还限制了 {literal} 内部不能再出现任何 ThinkPHP 标签，否则整个区块会被原样输出，失去变量解析能力。
立即学习“PHP免费学习笔记（深入）”；
- 多层循环优先用
{foreach name="list" item="vo"}+{$vo.child|default=[]}配合 PHP 层预处理，比纯模板嵌套更可控 - 需要条件分支时，用
{if}{elseif}{else}替代{switch}，前者兼容性更好，调试也方便 - 若必须用
{switch}，确保每个{case}块内只包含纯文本或{$var}，不加其他标签
缓存清理不彻底：为什么删了 Runtime/Cache 还报错
ThinkPHP 模板编译缓存分两层：一层是 Runtime/Cache 下的 PHP 文件，另一层是 Runtime/Temp 里的模板哈希映射表（template_*.php）。只清 Cache 目录，旧的哈希记录仍存在，框架会认为“这个模板没变”，跳过重新编译，继续执行已损坏的缓存文件。
更隐蔽的情况是，开发时开了调试模式（app_debug = true），但服务器部署后关了调试，导致模板缓存策略切换，本地测试正常的模板在生产环境因缓存未刷新而失效。
- 清缓存必须同时删掉
Runtime/Cache和Runtime/Temp两个目录 - 命令行下推荐用
php think clear:cache -t template（TP6）或php think clear:cache（TP5.1），比手动删更可靠 - 上线前检查配置：生产环境务必设
app_debug = false，并确认template.cache_path指向可写目录
调试开关与模板编译行为的关系
很多人以为 app_debug = true 就等于“每次重编译”，其实不是。TP 默认开启模板缓存，即使在调试模式下，只要模板文件 mtime 没变，依然会复用已编译的 PHP 文件。只有当模板内容实际改动，才会触发重新编译 —— 所以改了标签但没保存文件，或者用 IDE 保存了但文件系统延迟同步，都会让调试失效。
另一个坑是 template.auto_rule 设置为 false 时，模板引擎不会自动补全闭合标签，所有 {/xxx} 必须手写，漏一个就编译失败。这个选项默认是 true，但某些老项目或定制内核里被关掉了。
- 临时强制重编译：在模板顶部加一行注释，比如
{!-- force recompile --}，改完保存即可触发 - 验证当前模板规则：打印
Config::get('template')，重点看auto_rule和cache_path值 - 线上排查时，可在入口文件开头加
define('APP_DEBUG', true)临时打开调试，但切记上线前删掉
最麻烦的不是语法错，而是标签解析器把某段内容识别成了别的标签类型——比如把 {:date('Y-m-d')} 里的单引号当成标签结束符，后面内容全乱。这种问题得靠关闭缓存 + 查编译后 PHP 文件才能看清真实发生了什么。
