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