主题常用设置

设置先按业务域找

子比主题后台设置由 Codestar Framework 注册，源码集中在 inc/options/admin-options.php。不要只按页面视觉位置找字段，先按业务域判断：

如果不知道某个设置在哪里，优先在源码里搜字段标题、配置项 id 或 _pz('配置项')。例如邮箱设置会落到 mail_smtps、mail_host、mail_port；图片灯箱会落到 imagelightbox、imagelightbox_type。

常用功能配置顺序

上线前建议按这个顺序配置：

1. 基础信息：站点名称、Logo、描述、备案、页脚信息。
2. 链接结构：WordPress 固定链接、服务器伪静态。
3. 邮件系统：SMTP、发件人、邮件模板、测试邮件。
4. 用户系统：登录注册开关、验证码、协议、绑定邮箱或手机。
5. 内容展示：文章列表、文章页、缩略图、图片灯箱、懒加载。
6. 支付与会员：支付方式、订单回调、付费阅读、下载权限。
7. 消息通知：站内消息、私信、邮件通知、微信模板消息。
8. 缓存加速：页面缓存、对象缓存、CDN、静态资源。

这个顺序能避免很多连锁问题。比如登录验证码依赖邮件或短信；支付回调依赖固定链接和 HTTPS；图片灯箱和懒加载又容易被缓存插件、JS 合并压缩影响。

配置项不是孤立开关

子比主题很多开关会牵动业务流程。比如：

改设置后要同时确认前台、Ajax 和缓存。只看后台保存成功不代表功能完整可用。

基础显示字段地图

子比主题“基础配置和前端显示配置”主要分散在 basic、page、post 三个一级 section。排查时不要只看后台页面标题，应先判断字段最终影响的是头部输出、正文结构、CSS 变量、搜索框还是邮件发送。

这些字段大多最终走 _pz() 读取。页面和文章的局部覆盖则走 zib_get_post_meta()，例如页面布局宽度、页面头部、页面背景和单篇文章显示布局。

前台读取链路

基础配置落地到前台时有几个固定入口：

开发扩展时可以按这个顺序判断字段是否生效：后台字段保存成功，_pz() 能读到值，对应入口是否在当前页面执行，最终 HTML、body class 或 JS 变量是否输出。不要只在后台字段保存后就判断功能已完成。

Logo 与明暗模式

Logo 不是简单读取一张图片。主题提供日间和夜间两套 Logo，明暗模式由 zib_get_theme_mode() 决定：

function zib_get_theme_mode()
{
    $theme_mode = _pz('theme_mode');
    if (_pz('theme_mode_button', true) && isset($_COOKIE['theme_mode'])) {
        $theme_mode = $_COOKIE['theme_mode'];
    } else {
        $time = current_time('G');
        if ('time-auto' == $theme_mode) {
            if ($time >= 20 || $time < 8) {
                $theme_mode = 'dark-theme';
            } else {
                $theme_mode = 'white-theme';
            }
        }
    }
    return apply_filters('zib_theme_mode', $theme_mode);
}

这段逻辑有两个边界：

• 如果开启了主题切换按钮，用户 Cookie 优先于后台默认值。
• 如果后台设置为 time-auto，主题按站点当前时间早晚自动切换。

需要输出跟随主题切换的图片时，优先复用 zib_get_adaptive_theme_img()，它会写入 white-src 和 dark-src，前台切换主题时能同步替换图片地址。

function zib_docs_get_adaptive_logo($white_logo, $dark_logo)
{
    return zib_get_adaptive_theme_img($white_logo, $dark_logo, get_bloginfo('name'), 'class="custom-logo"');
}

懒加载字段

懒加载字段按图片出现位置拆分，不是一把总开关。主题底层判断：

function zib_is_lazy($key, $default = false)
{
    if (zib_is_crawler()) {
        return false;
    }

    return _pz($key, $default);
}

function zib_get_lazy_attr($key, $src, $class = '', $lazy_src = ZIB_TEMPLATE_DIRECTORY_URI . '/img/thumbnail.svg')
{
    return zib_is_lazy($key) ? ' class="lazyload ' . $class . '" src="' . $lazy_src . '" data-src="' . $src . '"' : ' class="' . $class . '" src="' . $src . '"';
}

几个细节要保留：

• 搜索引擎爬虫访问时会关闭懒加载，避免图片真实地址只存在于 data-src。
• 不同场景使用不同字段，文章缩略图用 lazy_posts_thumb，头像用 lazy_avatar，正文图片用 lazy_posts_content，封面图用 lazy_cover。
• thumbnail 是全局占位图，但很多模块会根据尺寸使用主题内置 thumbnail.svg、thumbnail-sm.svg 或 thumbnail-lg.svg。

新增图片输出建议使用主题函数：

function zib_docs_get_cover_img($src, $alt = '')
{
    if (!$src) {
        return '';
    }

    $alt       = $alt ? $alt : get_bloginfo('name');
    $lazy_attr = zib_get_lazy_attr('lazy_cover', esc_url($src), 'fit-cover radius8');

    return '<img ' . $lazy_attr . ' alt="' . esc_attr($alt) . '">';
}

布局与视觉字段

layout_max_width 会被 zib_get_page_max_width() 限制到不低于 1200px，并输出为 --mian-max-width。页面自身也可以通过页面 meta 覆盖宽度，前提是页面 meta 的值大于 1200。

侧栏布局由 _bodyclass() 统一输出：

视觉字段大多在 zib_head_css() 输出 CSS 变量：

扩展前台样式时优先消费这些 CSS 变量，而不是在模块里写死颜色和圆角。这样用户修改后台主题色、暗色主题色和圆角后，扩展模块能自然跟随。

搜索字段

搜索配置分为“搜索框展示”和“搜索执行”两层。

zib_get_main_search() 读取后台设置后交给 zib_get_search_box() 输出结构。搜索类型来自 zib_get_search_types()，并通过 search_types Filter 允许商城、论坛或自定义内容类型追加。

function zib_docs_search_types($types)
{
    $types['docs'] = __('文档', 'zib_language');

    return $types;
}
add_filter('search_types', 'zib_docs_search_types');

如果新增搜索类型，还要接管查询或结果 Tab。只加 search_types 只能让类型显示出来，不能保证 WordPress 主查询知道应该搜索什么内容。

热门搜索词不是纯前端展示。主题会在搜索时调用 zib_update_search_keywords() 记录关键词，并保存到 search_keywords option；后台设置保存后，搜索筛选数据还会通过 csf_zibll_options_saved 清理缓存。

邮件字段

SMTP 开关和字段最终挂到 WordPress 邮件系统：

function zib_mail_smtp($phpmailer)
{
    if (_pz('mail_smtps')) {
        $phpmailer->IsSMTP();
        $phpmailer->FromName   = _pz('mail_showname');
        $phpmailer->Host       = _pz('mail_host', 'smtp.qq.com');
        $phpmailer->Port       = _pz('mail_port', '465');
        $phpmailer->Username   = _pz('mail_smtp_name') ?: _pz('mail_name');
        $phpmailer->Sender     = _pz('mail_name', '88888888@qq.com');
        $phpmailer->Password   = _pz('mail_passwd', '123456789');
        $phpmailer->From       = _pz('mail_name', '88888888@qq.com');
        $phpmailer->SMTPAuth   = _pz('mail_smtpauth', true);
        $phpmailer->SMTPSecure = _pz('mail_smtpsecure', 'ssl');
    }
}
add_action('phpmailer_init', 'zib_mail_smtp');

邮件配置会影响验证码、找回密码、私信通知、站内消息通知、认证审核、举报处理、论坛审核和商城通知等场景。排查邮件问题时应先用后台测试邮件确认 wp_mail() 可用，再去看具体业务流程。

主题还通过 wp_mail Filter 包装邮件内容，使用 mail_description、mail_more_content 和 logo_src 生成统一邮件模板。扩展邮件通知时建议调用 zib_send_email() 或 wp_mail()，让它继续经过主题模板过滤，不要单独拼一套邮件 HTML。

开启功能前先确认依赖

很多“设置开了没效果”并不是设置项没保存，而是依赖没有满足。

保存设置后的排查

如果后台保存设置后前台没有变化：

1. 清理浏览器缓存。
2. 清理 WordPress 缓存插件。
3. 清理对象缓存，例如 Redis。
4. 清理服务器缓存，例如 Nginx fastcgi_cache。
5. 清理 CDN 缓存。
6. 确认当前页面没有命中旧模板或旧配置。
7. 搜索源码确认前台读取的是哪个 _pz() 配置项。

如果后台保存失败、弹 undefined 或一直转圈，优先看 admin-ajax.php 请求状态码，再看 PHP 错误日志、WAF、安全插件和 max_input_vars。

开发者查配置

读取主题设置用 _pz()：

$logo = _pz('logo_src');

if (_pz('imagelightbox')) {
    // 图片灯箱已开启
}

$smtp_host = _pz('mail_host', 'smtp.qq.com');

读取数组配置的子项：

$captcha_appid = _pz('tcaptcha_option', '', 'appid');
$bind_phone    = _pz('user_bind_option', false, 'bind_phone');

配置项默认值要在读取时兜底。用户可能从旧版本升级，数据库里没有新字段；也可能导入过不完整配置。

参考来源

本页吸收了子比官网“主题常用功能设置”类公开教程，并结合当前主题源码中的 inc/options/admin-options.php、inc/options/options-module.php 和 _pz() 读取方式整理为内置知识。