Smarty需完整复制libs目录（含sysplugins等子目录），路径须用绝对路径如__DIR__ . '/smarty/libs/Smarty.class.php'，PHP版本需≥7.2，模板目录为根路径，Linux严格区分大小写，文件须UTF-8无BOM，assign变量名与模板引用名必须一致，禁用方括号语法，缓存分编译与运行时两层，templates_c和cache目录须禁止Web访问。
Smarty 不是靠“学语法”就能用好的，它本质是个约束型协作工具——你越早接受“模板里不能写业务逻辑”这个前提，踩的坑就越少。
为什么 require_once './smarty/libs/Smarty.class.php' 总报错？
错误现象：Warning: require_once(...): failed to open stream 或 Class 'Smarty' not found
根本原因不是路径写错，而是没确认两件事：
-
libs/目录必须完整复制（含sysplugins/和plugins/子目录），缺一个文件就会中断加载 - 路径是相对于当前 PHP 脚本执行位置（
__DIR__），不是相对于项目根目录；建议统一用绝对路径：require_once __DIR__ . '/smarty/libs/Smarty.class.php'; - PHP 版本低于 7.2 会直接失败——
Smarty 3.1.40+已不兼容 PHP 5.x，且部分 3.x 旧版在 PHP 8.2+ 中触发弃用警告
setTemplateDir() 后 display('index.tpl') 还找不到模板？
常见错觉：只要路径对，index.tpl 放哪都行。实际规则更严格：
立即学习“PHP免费学习笔记（深入）”；
-
setTemplateDir()指定的是**根模板目录**，不是子目录；display('admin/user/list.tpl')表示文件路径是templates/admin/user/list.tpl，不能跨出该目录 - Windows 下路径分隔符混用（
\vs/）可能被忽略，但 Linux/macOS 严格区分大小写——Index.tpl≠index.tpl - 模板文件必须保存为 UTF-8 **无 BOM** 格式，否则
{if}等标签前出现不可见字符，导致解析失败，错误提示却指向其他行
assign() 传数组，模板里 {foreach $data as $item} 却遍历不出？
这不是语法错，是数据结构预期 mismatch：
-
assign('data', $arr)后，模板中变量名就是$data，不是$arr；命名必须完全一致 - 若
$arr是关联数组（如['name' => '张三', 'age' => 28]），{foreach $data as $k => $v}才能取键值；只写{foreach $data as $v}只能取值 - 多维数组嵌套时，
{$item.children.0.name}合法，但{$item['children'][0]['name']}会报错——Smarty 模板不支持方括号语法，一律用点号 - 对象属性需显式暴露：
$obj = new StdClass(); $obj->name = '李四'; $smarty->assign('user', $obj);，模板中才可用{$user->name}
缓存开启后页面不更新，clearCache() 也不生效？
缓存机制有两层：编译缓存（templates_c/）和运行时缓存（cache/），常被当成一回事：
-
clearCache()只清cache/下的 HTML 缓存；改了.tpl文件但页面不变，大概率是templates_c/里的编译 PHP 文件没重生成——关掉compile_check = false（开发期务必设为true） -
caching = Smarty::CACHING_LIFETIME_CURRENT表示按模板文件修改时间判断是否过期；若服务器时间不准或模板文件被覆盖但时间戳未更新，缓存就永远不刷新 - 生产环境禁用
debugging = true，否则每次请求都会输出调试窗口，不仅暴露目录结构，还强制跳过部分缓存逻辑
最易被忽略的一点：templates_c 和 cache 目录必须禁止 Web 直接访问——Apache/Nginx 配置里要明确 deny all，否则别人能直接下载编译后的 PHP 文件，看到你所有数据库查询和逻辑。
