Z-Blog 主题从零搭起来：theme.xml 到底要写哪几行

网上讲 Z-Blog 主题开发的文章，一上来就是「复制一份默认主题改改」。能用。但你不知道哪些文件是必须的，哪些可以删。

我第一份主题是从 default 里删文件删出来的。删到最后只剩五个文件，站还能跑。

theme.xml 决定主题能不能被识别

Z-Blog 后台「主题管理」列出来的每一行，来源是主题目录下的 theme.xml。没有这个文件，目录放进去也不显示。

最小可用版本大概长这样：

<theme> 根节点里放 <id>、<name>、<url>、<note>、<author>、<style>。

几个容易踩的点：

id 必须和目录名一致。 目录叫 framehome，id 写成 FrameHome，后台能显示，但启用时会去找 zb_users/theme/FrameHome/，找不到，报错。

style 节点不是可有可无。 它下面挂 <name> 和 <file>，file 指向 style/ 目录里的 css。可以是相对路径，也可以直接写完整 URL。少了这个，后台「主题样式」下拉是空的，选不了。

note 里的文字不要塞 HTML。 后台会转义显示，标签全变成可见字符。

模板文件不是全都要有

Z-Blog 的模板查找有一套回退规则。你要的文件不存在，它会往上找。

必须有的大概是这几个：

index.php、single.php、sidebar.php、header.php、footer.php、comment.php。

其余全是可选。page.php 没写，页面就走 single.php。category.php 没写，分类页走 index.php。search.php 没写，同样回退。

所以「最小主题」为什么能跑：只要 index.php 把所有内容用循环打出来，别的页面全靠回退，也能看。

不好看而已。

include.php 是我最后才知道的东西

主题目录下的 include.php，在主题被启用时自动加载。它不输出任何内容，作用是注册钩子。

我一开始以为它和 WordPress 的 functions.php 完全等价，后来发现只对了一半。functions.php 能写业务逻辑，Z-Blog 的 include.php 主要是挂 Filter，业务代码写多了容易在后台白屏——因为它在很早期就被 include。

有个具体后果：在 include.php 顶层直接查数据库，后台登录页都可能挂。 我踩过一次，那次是插件冲突排查了半天，最后发现是自己主题里有个 $zbp->LoadArticleList() 写在最外层。

正确做法是包进钩子函数，等系统准备好再执行。

目录结构建议

我现在的习惯是这样：

模板文件平铺在根目录，不放子目录；样式扔 style/；图片扔 img/；需要引入的公共片段放 template/，用 {template:xxx} 调。

平铺的好处是回退规则和文件名一一对应，你看到 tag.php 就知道它管标签页。塞子目录反而要在 include.php 里做映射，纯属自找。

最后说个验证办法

搭完之后别急着建内容。把 zb_users/cache/ 清空，然后逐页访问首页、文章页、分类页、标签页、搜索页、404。

六个页面都能出内容，说明框架通了。剩下的只是样式。

要是某个页面白屏，先看 zb_users/logs/ 有没有报错文件。多半是模板里写了不存在的变量。

这个顺序别反过来，一上来抠样式，后面改框架等于重做。