关于Smarty，很多人的学习心态一开始就偏了。
它不是什么高深的模板语言，更不是靠死记语法就能掌握的东西。说穿了，Smarty就是一个约束型协作工具——你越早接受“模板里不能写业务逻辑”这个前提，后面踩的坑就越少。
话不多说，先捋一捋几个最常见、也最让人头疼的坑。
为什么 require_once 总报错？
你可能会收到这样的报错：Warning: require_once(...): failed to open stream，或者是 Class 'Smarty' not found。
很多人第一反应是路径写错了。其实这只是表面原因，真正的问题出在两个方面。
第一，libs/ 目录必须是完整复制的。 它下面有 sysplugins/ 和 plugins/ 这些子目录，缺一个文件都会导致加载中断。别想着只复制主文件就行，没那么简单。
第二，路径的写法要特别注意。 require_once 是相对于当前 PHP 脚本的执行位置，不是项目根目录。最稳妥的办法是统一用绝对路径：require_once __DIR__ . '/smarty/libs/Smarty.class.php';
还有一个容易被忽视的细节：PHP 版本。Smarty 3.1.40+ 已经不再兼容 PHP 5.x，如果你还在用老版本，直接就会失败。而且部分 3.x 的旧版在 PHP 8.2+ 上会触发弃用警告。所以，确保你的 PHP 版本在 7.2 以上，这是硬性门槛。
setTemplateDir() 之后，模板还是找不到？
很多人以为，只要路径写对了，模板文件放哪都行。但实际规则比想象中严格。
首先，setTemplateDir() 指定的是根模板目录，不是子目录。如果你写 display('admin/user/list.tpl')，那这个文件的实际路径必须是 templates/admin/user/list.tpl，不能跨出这个目录。
其次，Windows 下路径分隔符混用（\ 和 /）可能被忽略，但如果你在 Linux 或 macOS 上，大小写是严格区分的。Index.tpl 和 index.tpl 完全是两个文件。
还有一个很容易掉进去的坑：模板文件必须保存为 UTF-8 **无 BOM** 格式。否则，{if} 等标签前面会出现不可见字符，导致解析失败，而且错误提示往往指向其他行，排查起来非常头疼。
assign() 传了数组，模板里遍历不出来？
这看起来像是语法错误，但实际上是数据结构预期不匹配。
核心规则很简单：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() 也不管用？
缓存这部分，很多人的理解是混淆的。Smarty 的缓存机制实际上有两层：编译缓存（templates_c/）和运行时缓存（cache/）。很多人把它们当成一回事，于是出了问题就找错方向。
clearCache() 只清理 cache/ 下的 HTML 缓存。如果你改了 .tpl 文件但页面没有变化，那大概率是 templates_c/ 里的编译 PHP 文件没有重新生成。开发期间务必把 compile_check 设为 true，否则改了模板等于白改。
caching = Smarty::CACHING_LIFETIME_CURRENT 的意思是按模板文件的修改时间来判断缓存是否过期。但如果服务器时间不准，或者模板文件被覆盖但时间戳没更新，那缓存就永远不会刷新。
还有一个小提醒：生产环境要关掉 debugging = true。否则每次请求都会输出调试窗口，不仅暴露目录结构，还会强制跳过部分缓存逻辑，性能会受影响。
最容易被忽略的一点：templates_c 和 cache 这两个目录必须禁止 Web 直接访问。在 Apache 或 Nginx 配置里要明确设置 deny all，否则别人可以直接下载编译后的 PHP 文件，看到你所有的数据库查询和业务逻辑。这已经是安全底线了。
Smarty 的学习路径其实不复杂，把上面这几个坑提前摸清楚，后面走起来就顺多了。
