主题配置项怎么做？从后台设置到前台输出，别只做表单不落地

很多主题第一版都喜欢把内容写死：

• 首页标题写死
• 默认缩略图写死
• CTA 文案写死
• 页脚说明写死

这样起步快，但主题一旦要维护，就会很难受。

因为你很快就会碰到这些问题：

• 改一句首页文案还得改代码
• 默认图片变了还得进模板找路径
• 某个模块要不要显示，没法后台开关
• 不同站点复用同一主题时，每次都得手工改文件

所以一个真正能用的主题，迟早要做配置项。

这一篇我们就把这条链路讲完整：

后台怎么做配置，配置怎么保存，前台又怎么把它用起来。

一、先分清：什么东西适合做成主题配置

不是所有东西都该做成配置项。

更适合做成主题配置的，通常是这些：

• 首页主标题
• 首页副标题
• 默认缩略图
• 页脚版权文案
• 某个首页模块开关
• 列表摘要长度
• 主题级 SEO 默认值

这些东西有一个共同点：

它们属于全局设置，而不是某篇文章自己的数据。

所以它们更适合放进主题配置，而不是塞进文章字段里。

二、Z-BlogPHP 里，主题配置通常放在哪

主题或插件的全局配置，通常会走：

$zbp->Config('AppID')->SomeKey = $value;
$zbp->SaveConfig('AppID');

读取时也很直接：

$value = $zbp->Config('AppID')->SomeKey;

这意味着你做主题配置时，核心其实就是三件事：

1. 后台给它一个表单入口
2. 保存时写进 Config
3. 前台读取并参与渲染

三、从流程上看，主题配置项通常会经过这 4 步

第 1 步：决定配置项长什么样

比如你准备先做这三个：

• 首页主标题 HomeHeroTitle
• 首页副标题 HomeHeroSubtitle
• 默认缩略图 DefaultThumb

先把名字定清楚，后面会省很多麻烦。

第 2 步：在后台设置页输出表单

也就是主题的 main.php。

第 3 步：保存时写入 Config

保存逻辑通常还是在 main.php 里。

第 4 步：前台模板或主题逻辑读取

最终常见落点会是：

• include.php
• header.php
• index.php
• single.php

四、后台设置页保存逻辑，最核心的是这几件事

主题后台页的保存逻辑，重点不是“表单长什么样”，而是流程要完整。

比较稳的顺序通常是：

1. 接收提交
2. CheckIsRefererValid()
3. 读取表单值
4. 写入 Config
5. SaveConfig()
6. 需要时执行 BuildTemplate() 或其他重建
7. 成功提示或跳转

一个简化示意大概像这样：

if (count($_POST) > 0) {
    CheckIsRefererValid();

    $zbp->Config('MyTheme')->HomeHeroTitle = trim(GetVars('HomeHeroTitle', 'POST'));
    $zbp->Config('MyTheme')->HomeHeroSubtitle = trim(GetVars('HomeHeroSubtitle', 'POST'));
    $zbp->Config('MyTheme')->DefaultThumb = trim(GetVars('DefaultThumb', 'POST'));

    $zbp->SaveConfig('MyTheme');
    $zbp->BuildTemplate();
    $zbp->SetHint('good');
    Redirect('./main.php');
}

你会发现真正关键的是：

• 提交安全校验
• 配置写入
• 保存
• 重建

这才是“配置项能落地”的骨架。

五、为什么保存配置时常常要 CheckIsRefererValid()

很多人写后台保存逻辑时，容易把这一步忘掉。

但它很重要。

因为主题配置页本质上是后台写操作。

只要是写操作，就不应该只是：

• 用户打开页面
• 发个 POST
• 系统就无条件保存

`CheckIsRefererValid()`` 的作用，可以理解成：

给后台保存动作补一层基础校验。

你后面写插件设置页时，这个习惯也同样重要。

六、什么时候要 BuildTemplate()，什么时候不一定要

这也是很多人第一次做配置时容易迷糊的地方。

如果一个设置会影响前台渲染结果，比如：

• 首页标题
• 模块显示
• 页脚文案
• 头部 meta

那保存之后往往要考虑重建模板相关结果。

这时常见就会用到：

$zbp->BuildTemplate();

如果改的是模块结构、缓存结果，还可能涉及：

• BuildModule()
• SaveCache()

你不用机械地每次都全重建，但至少要建立这个意识：

保存成功，不等于前台立刻按你期待刷新。

有些改动和模板、模块、缓存是有关联的。

七、前台怎么读取主题配置，才不会越写越乱

这里最容易犯的错是：

• 模板里到处直接读配置
• 读不到时没有兜底
• 同一个配置在多个模板写重复判断

更稳的写法一般有两种。

写法 1：模板直接读取简单值

如果逻辑非常简单，模板里直接读也可以：

{php}
$heroTitle = $zbp->Config('MyTheme')->HomeHeroTitle;
{/php}

但这种方式更适合很轻的场景。

写法 2：在 include.php 里统一做兜底

比如：

function MyTheme_GetDefaultThumb() {
    global $zbp;
    $thumb = $zbp->Config('MyTheme')->DefaultThumb;
    return !empty($thumb) ? $thumb : $zbp->host . 'zb_users/theme/MyTheme/assets/default-cover.jpg';
}

这样前台模板拿到的是一个已经处理过的结果。

只要配置项开始有：

• 默认值
• 兜底逻辑
• 路径拼接
• 多模板复用

我都更建议你回到 include.php 统一处理。

八、一个完整的配置示例该怎么想

假设你要做“首页主视觉配置”。

这类需求通常包括：

• 主标题
• 副标题
• 主按钮文案
• 是否显示该区块

这时候最自然的拆法就是：

后台配置层

提供四个表单项：

• HomeHeroTitle
• HomeHeroSubtitle
• HomeHeroButtonText
• HomeHeroEnabled

保存层

写入主题 Config。

前台消费层

在首页模板或相关辅助函数里做：

• 读值
• 空值兜底
• 开关判断

这样这套配置才算真正闭环。

九、主题配置和文章字段，不要混着用

这一点必须强调。

适合做主题配置的

• 默认缩略图
• 页脚文案
• 首页大标题
• 首页模块开关

不适合做主题配置的

• 某一篇文章专属 SEO 标题
• 某一篇文章专属封面图
• 某个分类自己的描述

这些更适合用 Metas。

如果你把文章级数据硬塞进主题配置，后面编辑体验会非常糟糕。

十、做主题配置时最常见的 6 个坑

1. 只做表单，不做前台消费

后台能保存，但前台根本没读。

2. 只做保存，不做默认值兜底

结果一旦配置为空，模板就开始出现空块。

3. 忘记 CheckIsRefererValid()

这是后台保存流程里很容易漏的一步。

4. 保存后不重建相关结果

导致你误以为配置没生效。

5. 把复杂逻辑全塞模板里

前台一旦开始多处使用，维护会越来越痛。

6. 把对象级字段错做成主题全局设置

这会直接把内容编辑流程弄乱。

十一、做完配置项以后，至少这样验证

不要只看“后台保存成功”。

至少要验证：

• 表单值能正确保存
• 刷新后台后能读回原值
• 前台确实读取到了配置
• 空值时有兜底
• 相关模板更新正常
• 多页面使用同一配置时结果一致

这才是真正的“配置项做完了”。

结语

主题配置项的本质，不是做几个输入框，而是把：

• 后台表单
• 提交安全
• 配置保存
• 模板重建
• 前台消费

这一整条链路做通。

只要你把这套闭环做顺了，后面再加首页配置、默认图、模块开关、SEO 默认值，就都会顺很多。

下一篇我们进入插件开发入门，讲 RegisterPlugin、Add_Filter_Plugin、main.php 这些东西到底怎么配合。