首页 / 开发手册 / 模板引擎

模板引擎

标签是怎么编译的、缓存在哪、调试时怎么办。

编译过程

模板源码
   ↓ 按 <script> / <style> 切分
   ↓ 普通片段:编译块标签、单标签、裸变量
   ↓ 脚本片段:只编译 {naicha:...},其余花括号原样保留
   ↓ 生成 PHP
   ↓ 写入 storage/cache/tpl_<hash>.php
   ↓ 之后直接执行缓存

缓存策略(⚠️ 键里有三样东西,不只是"内容")

key = md5( 模板文件的绝对路径 | 文件的 mtime | Template::VERSION )
  • 模板改动(mtime 变了)→ 换一个文件名 → 自动重新编译,不用手动清缓存
  • 只是 touch 了一下、内容没变 → 也会重编一次(无害,多花几毫秒)
  • 覆盖部署会把 mtime 刷成新值 → 全站模板集体重编一次。这是设计取舍,不是故障

⚠️ 改了编译规则必须升 Template::VERSION

这是模板引擎最要紧的一条运维纪律。缓存键里带着引擎版本号,就是为了这件事:

// core/Template.php
const VERSION = '1.7.0';   // 动了 BLOCK_TAGS、标签语法、编译产物结构 —— 必须 +1

不升版本会怎样:线上那台机器上已经躺着一堆按旧规则编译好的 PHP, 键没变 → 继续用旧的 → 新标签不生效、新语法不认。 而代码、模板文件、清缓存命令看起来全都没问题 —— 你会去怀疑标签写错了、主题没切对、缓存没清干净,唯独想不到"编译产物是旧的"。

反过来:只改模板内容(不碰编译规则)不用升版本,mtime 变了自然会重编。

主题目录怎么找文件(子主题 → 父主题)

templates/<当前主题>/x.html        ← 先找这里
templates/<当前主题>/<语言>/x.html  ← 语言子目录优先
templates/<父主题>/x.html          ← 找不到就顺着 theme.json 的 parent 往上找

所以子主题只需要放"与父主题不一样"的那些文件, 其余自动继承 —— 子主题不等于要再维护一份完整代码。 theme.json 里的 parent 决定上一级是谁,最多向上找 8 层(写成了环也不会把站点转死)。

⚠️ 模板不在主题里:它在顶层 admin/, 由 AdminController 显式指定。所以那几个文件(header/footer)不受主题切换影响 —— 也正因为如此,模板里的 {naicha:include file="header.html"} 用的是自己那一份,不是前台的。

为什么要区别对待 script 片段

JavaScript 里大量使用花括号:对象字面量、函数体、模板字符串。 如果一律把 {...} 当成模板变量,JS 会被编译得面目全非。 所以脚本块内只认带 naicha: 前缀的明确标签, 同时给少数几个脚本里确实需要的宿主变量开了白名单。

几条配套的语法规则(细节看「标签」那几篇)

规则说明
{{name}}转义写法:原样输出 {name},不当变量解析(想在页面上显示一个花括号时用)
HTML 注释里的标签不生效,原样输出(浏览器不显示)。想在输出里保留注释要写 <!--+ … +-->
{naicha:include file="…"}只取文件名(basename),写路径穿越无效;找不到就回落到父主题
HTML 注释编译时被剥掉,不进输出 —— 页面上不会出现"写了但被输出"的注释

调试

  1. 页面出现意料之外的字面量 {list.title}:多半是标签名或闭合标签写错了 (认不出的标签会被静默吞掉,既不算错也不原样输出)
  2. 循环里取不到值:确认字段确实存在于该标签的作用域。 自定义字段直接写字段名就行(引擎会自动去 ext 里找),写 {list.ext.xxx} 也等价
  3. 改了模板没生效,按这个顺序查: ① 改的是不是当前启用主题目录下的文件(子主题有同名文件时,父主题那份根本不参与); ② 主题配置里 parent 指向谁; ③ 是不是动了编译规则却没升 Template::VERSION(见上面那一节); ④ 最后才是「清模板缓存」
  4. 整块内容消失、页面其余正常:九成是块标签忘写闭合,见「套标签与失败模式」那篇的失败模式表
编译前的模板不会执行:模板是数据,不是代码。 即使模板文件被泄露,其中也没有可直接执行的逻辑,更无法访问数据库。
没找到答案? 可以在 联系我们 留言说明使用场景,我们会补充进文档。