Z-Blog 主题开发入门：模板标签、include 机制与自定义字段

先说结论：Z-Blog 主题开发只需要理解三件事——模板文件与命名约定、模板标签的取数方式、include 与自定义字段的扩展点。掌握这三点，改任何主题都不再靠猜。

一、目录与文件约定

主题放在 zb_users/theme/主题ID/，核心是 theme.xml 与一组模板文件。模板文件名决定它被用在哪个位置（首页、列表、详情、单页、搜索等），命名约定即是路由。改主题前先看清哪个页面用了哪个文件，避免改了不生效。

二、模板标签：取数靠标签，不是靠 SQL

• 列表类数据用对应的列表标签，注意分页参数与「只取 N 条」的写法。
• 详情页数据通过全局对象获取，字段名与后台字段一一对应。
• 条件判断用内置的条件标签，不要为了一个 if 去写 PHP。

经验：能在模板里拿到的数据就不要在模板里查库，这是主题性能的第一道分水岭。

三、include 机制

公共头部、底部、侧栏通常抽成独立文件再用包含标签引入。两个要点：

1. 被 include 的文件不要重复声明输出编码，避免页面出现乱码头部。
2. 传入局部变量时注意作用域，包含文件里拿不到外部临时变量是新手最常见的问题。

四、自定义字段

主题想给文章加额外信息（如封面图、副标题、来源），标准做法是走自定义字段：

• 后台通过字段配置声明，前端用 meta 方式输出。
• 输出前一定要做存在性判断与转义，避免空值破坏布局、避免注入。
• 批量修改字段时优先用脚本或插件，不要一篇篇手改。

五、发布前检查清单

• 不同分辨率下不溢出、不遮挡。
• 无数据时（空分类、零评论）页面不崩。
• 关闭调试模式后无报错、无残留调试输出。
• 版本号写入 theme.xml，方便后续升级识别。

把这三件事吃透，主题开发就从「照着别人抄」变成「按需求搭」。