一份实战提炼的 Z-Blog 主题开发指南

最近在开发 maker.jiuhui.net 的 Z-Blog PHP 主题过程中，踩了不少坑——从模板编译管线的理解到 BuildTemplate() 的反模式，从数据库配置到 PHP-FPM 的兼容处理——索性把这些经验系统地整理成了一份开发指南，已经放到了知识库里。

这份指南基于 Z-Blog PHP 1.7.5 的实战经验写成，涵盖完整开发流程、关键踩坑和最佳实践，AI agent 和开发者都能照着做而不出错。

指南的核心内容

1. 架构理解——Z-Blog 模板引擎是类 Smarty 但不是 Smarty，很多人直接当 PHP 写，结果编译报错。指南从 LoadTemplates() → CompileFile() → Display() 的完整流水线讲清楚。

2. BuildTemplate() 反模式——这是最隐蔽的坑。某些教程推荐在 include.php 里手动编译模板，但 Z-Blog 1.7.5 的自动编译机制已经够用了，手动调用 BuildTemplate() 反而导致编译输出错乱和 Fatal Error。

3. 完整模板语法参考——包括文章调用（{$article.Title}）、分类（{$category.Name}）、分页（{$pagebar}）、导航高亮（{$currentPage}）等，附默认模板源码对照。

4. 安全与兼容——Security Header 必须声明、PHP-FPM vs mod_php 的处理差异、插件冲突的排查方法。

5. 踩坑案例全集——编译缓存不更新时清哪几个目录、PHP-FPM 模式下某些函数的兼容性问题、include.php 加载顺序引发的 null 对象调用。

为什么需要这份指南

Z-Blog 官方文档对主题开发覆盖有限，社区资料散乱且很多过时。这份指南是"做了再写"——每一条经验都是实际部署中遇到过、解决过的，不是照搬官方文档。特别是对 AI agent 开发 Z-Blog 主题的场景，指南里明确的目录结构、文件命名规范、缓存清理步骤，能省掉大量试错时间。

指南全文已归档到内部知识库（wiki-v3），以后开发新主题或者排查主题问题，先翻翻它再动手。