从零认识 Z-BlogPHP 主题开发：先搭最小骨架，再谈首页效果

前面几篇我们已经把环境、运行流程、文件职责讲清了。现在终于可以进入很多人最关心的部分：

Z-BlogPHP 主题到底怎么开始写？

但这里我不打算一上来就讲复杂首页，也不打算直接把一堆模板文件摊给你。

更好的起点是先回答这件事：

一个“最小可用”的 Z-BlogPHP 主题，结构应该长什么样？

只要这层搞明白，后面你再加首页、分类页、文章页、设置页，都会有地方可落。

一、先建立一个正确预期：主题不是只有模板

很多新手第一次做主题，会把主题理解成：

• 几个 HTML 页面
• 一份 CSS
• 一点头部和页脚

这当然是主题的一部分，但不完整。

一个真正能长期维护的 Z-BlogPHP 主题，至少要同时承接这几件事：

• 主题元信息
• 前台模板输出
• 主题逻辑
• 主题后台设置
• 样式和脚本资源

所以你后面写主题时，思路一定不要停在“拼页面”。

更准确一点，主题是：

前台外观 + 一部分展示逻辑 + 一部分主题级配置能力。

二、最小可用主题结构，先看这一版

如果你要从零搭一个最小可用主题，建议至少准备到这个层级：

zb_users/theme/<theme>/
├── theme.xml
├── include.php
├── main.php
├── template/
│   ├── header.php
│   ├── footer.php
│   ├── index.php
│   └── single.php
├── style/
│   └── style.css
├── script/
└── assets/

这是一个很实用的最小骨架。

为什么说它够用？

因为它已经覆盖了：

• 主题声明
• 主题逻辑入口
• 后台设置入口
• 列表页
• 详情页
• 公共头尾
• 基本样式

对一个开发起点来说，这已经足够往上继续长。

三、theme.xml 是主题的身份证

很多人刚开始做主题，最容易忽略这个文件。

但从系统角度看，主题先得“被识别为一个主题”，后面才谈得上启用和管理。

theme.xml 主要负责这些信息：

• 主题 ID
• 主题名称
• 描述
• 作者
• 后台入口路径
• 逻辑入口文件

你可以把它理解成：

系统先读到这里，才知道这个目录里的东西是个主题。

一个简化后的示意结构，大概像这样：

<?xml version="1.0" encoding="utf-8"?>
<theme version="php">
  <id>MyTheme</id>
  <name>My Theme</name>
  <note>一个用于内容站开发的示例主题</note>
  <path>main.php</path>
  <include>include.php</include>
  <level>1</level>
  <author>
    <name>Your Name</name>
  </author>
</theme>

这里最重要的不是把所有字段背下来，而是知道：

• 主题 ID 要稳定
• 目录名最好和主题 ID 保持一致
• include.php 和后台入口会在这里挂上

四、为什么我建议一开始就保留 include.php

有些人做第一个主题时，会想：

• 先不写逻辑
• 先只做模板
• include.php 以后再说

理论上可以，但实践里不推荐。

原因很简单：

只要你的主题开始做下面任意一件事，include.php 很快就会变得必要：

• 注册主题逻辑
• 放通用辅助函数
• 读取主题配置
• 条件加载资源
• 做多模板复用逻辑

所以最稳的做法是：

即使第一版逻辑很少，也先把 include.php 这个入口留好。

后面才不会越写越散。

五、main.php 为什么也建议尽早留出来

很多新手第一版主题还没开始做设置，就把 main.php 省掉了。

这也不是完全不行，但如果你想让主题具备基本维护能力，后台入口最好尽早留着。

因为很快你就会遇到这类需求：

• 首页主标题可配置
• 默认缩略图可配置
• 列表页摘要长度可配置
• 页脚文案可配置
• 某个模块开关可配置

这些都不适合硬编码写死。

所以 main.php 的意义不是“把后台做复杂”，而是给主题预留一个能进化的设置入口。

六、模板目录最少先准备哪些文件

如果是第一版主题，我建议先准备这四个：

1. header.php

负责：

• 文档头部
• 全局 CSS
• 站点头部结构
• {$header} 输出

2. footer.php

负责：

• 公共页脚
• 全局尾部脚本
• {$footer} 输出

3. index.php

负责：

• 首页
• 列表页
• 常见归档页

4. single.php

负责：

• 文章详情页

只靠这四个文件，你就已经可以做出一个最小可用主题。

后面再按需要补：

• page.php
• search.php
• comments.php
• 404.php
• 侧栏或导航模板

七、最小模板组合应该怎么写

Z-BlogPHP 的模板开发，不是把所有页面写进一个大文件里。

更常见的做法，是拆公共部分再组合。

比如：

{template:header}

<main class="site-main">
  {foreach $articles as $article}
    <article class="post-card">
      <h2><a href="{$article.Url}">{$article.Title}</a></h2>
      <p>{$article.Intro}</p>
    </article>
  {/foreach}
</main>

{template:footer}

这段结构的重点不是样式，而是思路：

• 头尾独立
• 页面主体独立
• 列表循环直接使用模板变量

详情页也类似：

{template:header}

<article class="post-single">
  <h1>{$article.Title}</h1>
  <div class="post-content">{$article.Content}</div>
</article>

{template:footer}

这就是“最小主题”的真实出发点。

八、样式和脚本目录为什么也别省

有些人图快，会把：

• CSS
• JS
• 图片

全塞在一个地方。

短期能跑，长期很乱。

哪怕是最小主题，也建议先分清这三层：

style/

放主题主样式和拆分样式。

script/

放主题自己的前端脚本。

assets/

放图标、图片、字体、通用静态资源。

这不是形式主义，而是为了以后你做：

• 资源按需加载
• 样式拆分
• 多页面资源管理

时不至于返工。

九、主题开发时，哪些逻辑一开始就别写太重

第一次做主题，最容易过度设计。

下面这些东西，建议你第一版不要一上来就做太复杂：

1. 把所有页面类型一次写全

先让：

• 列表页
• 详情页
• 公共头尾

跑通，更重要。

2. 把所有派生逻辑塞模板里

如果缩略图、摘要、时间格式这些逻辑开始复杂，尽早回 include.php。

3. 过早造很多抽象层

Z-BlogPHP 主题开发本来就偏直接。

第一版结构清楚，比抽象漂亮更重要。

4. 一开始就做一堆主题设置

建议先把真正需要编辑的 2 到 3 个全局设置做好，其他等页面稳定再加。

十、一个更稳的主题起步顺序

如果你准备从零做一个主题，我建议按这个顺序：

1. 先建好目录骨架
2. 写 theme.xml
3. 留出 include.php
4. 留出 main.php
5. 写 header.php 和 footer.php
6. 写 index.php
7. 写 single.php
8. 接主样式
9. 再补搜索、评论、404、独立页面

这个顺序的好处是：

• 系统能先识别主题
• 结构先站住
• 列表和详情这两条主线先跑通
• 后面再继续增量开发

十一、第一次做主题最常见的 5 个坑

1. 只有模板，没有逻辑入口

后面一加配置和复用逻辑就开始乱。

2. 一开始就把 index.php 写成大杂烩

更好的方式是：

• 先把结构跑通
• 再拆公共片段
• 再把复用逻辑抽回 include.php

3. theme.xml 和目录名不稳定

后面维护和迁移都容易出问题。

4. 样式、脚本、图片混放

短期看不出问题，后面资源会越来越难管。

5. 主题职责和插件职责混在一起

前台外观是主题主战场。

评论校验、后台扩展、通用流程接管，不要一股脑都塞进主题。

结语

Z-BlogPHP 主题开发的起点，不是“先做一个很好看的首页”，而是先搭一个职责清晰、能继续生长的最小骨架。

你只要先把下面这套结构立住：

• theme.xml
• include.php
• main.php
• template/header.php
• template/footer.php
• template/index.php
• template/single.php
• style/
• script/
• assets/

后面加页面、加配置、加逻辑，都会顺很多。

下一篇我们继续往前走，专门讲模板开发实战：首页、列表页、文章页、搜索页，到底应该怎么拆。