ZBlog应用中心开发者规范，从主题调试到插件排错的实战手册

主题安装后首页空白，怎么排查？

老周（干了七年ZBlog主题开发的自由职业者）凌晨两点接到客户电话：“首页啥也没有，白屏！”他叹了口气，打开终端，敲下第一步。

排查步骤：

ZBlog应用中心开发者规范，从主题调试到插件排错的实战手册

检查主题是否完整上传
进入 /zb_users/theme/你的主题名/，确认 template/ 目录下至少有 index.php、header.php、footer.php 三个文件，缺一个，首页就会空白。
开启调试模式
在 zb_users/c_option.php 中添加：
```
return array(
    'DEBUG_MODE' => true,
    'DEBUG_TYPE' => 'E_ALL',
);
```
刷新首页,浏览器会显示具体的PHP错误行号，常见错误是 Undefined variable 或函数名拼写错误。
检查模板循环代码
若首页有文章列表但为空白，多半是循环未开启，在 index.php 中必须有：
```
<?php foreach ($articles as $article) { ?>
    
<?php } ?>
```
若 $articles 未定义，检查主题目录下是否有 include.php，并确认它调用了 $this->template->SetCaching() 且正确加载了文章数据。
缓存问题
如果之前亮过，突然空白，删除 /zb_users/cache/ 下所有文件（保留 index.html 和 .htaccess），再刷新。

侧边栏模块怎么按自己的顺序排？

新手小林在客户群里问：“我想把“最近评论”放最上面，但后台拖不动。”老周直接甩来一行命令。

方法：

后台可视化排序
后台 → 网站设置 → 侧边栏，拖拽模块即可，但如果主题禁用了默认侧边栏，此方法无效。

代码级控制
打开主题的 include.php，在 AppCentre 初始化函数中注册侧边栏：

public static function Init() {
    $sidebar = new ZBModule();
    $sidebar->SetName('当前主题专属侧边栏');
    $sidebar->SetCode('<ul>特制HTML</ul>');
    $sidebar->SetType('div');
    $sidebar->SetOrder(1); // 数字越小越靠前
    $sidebar->Save();
}

然后在 template/sidebar.php 中输出：

<?php $this->module->GetModules(); ?>

强制排序
在 footer.php 底部插入：

$order = array('calendar', 'comments', 'tags');
$this->module->SetSort($order);

插件安装后功能不生效？三步排查法

插件作者老王遇到的经典问题：“用户安装了最新版，但前台一点反应没有。”他打开远程协助，开始操作。

排查流程：

检查插件是否被启用
后台 → 应用中心 → 已安装，确认插件状态为 已启用，若为灰色，点击“启用”后刷新。
检查钩子是否加载
在 zb_users/plugin/你的插件名/include.php 中，必须注册钩子：
```
Add_Filter_Plugin('Filter_Plugin_Zbp_MakeTemplatetags', 'my_plugin_tpl_tag');
```
注意钩子名是否与主题冲突,若主题也注册了同名钩子，插件会被跳过。
检查函数名冲突
如果插件使用 function GetMyData()，而主题或另一个插件已定义同名函数，PHP会直接报错，用 function_exists('GetMyData') 先检测：
```
if (!function_exists('GetMyData')) {
    function GetMyData() { /* ... */ }
}
```

主题模板文件怎么改才安全？

老周给客户演示改 post.php 时被问：“为什么我改了没变化？”他回答：“十有八九改了缓存。”

修改指引：

定位文件
单篇文章页面是 /zb_users/theme/你的主题/template/ 下的 post.php（或 single.php），如果主题支持多模板，文件名可能带后缀，如 post-article.php。
修改后必须清缓存
登录后台，网站设置 → 缓存设置，点击“清空缓存”，或直接删除 /zb_users/cache/ 下所有文件。
模板标签用了没反应？
比如你想显示文章点击量，在 post.php 中加入：
```
<?php echo $article->ViewNums; ?>
```
若无效,检查是否在循环外（单篇文章页面不需要循环），如果是列表页（index.php），需在循环内使用。
避免直接改官方主题
建议复制一份到 theme/ 下改名，再修改，避免升级时被覆盖。

常用模板标签调用速查

小林在群里问：“有没有一份常用标签清单？”老周把笔记本截图发过去。

| 用途 | 代码 | 说明 | |------|------|------|| <?php echo $article->Title; ?> | 列表页循环内 | | 文章链接 | <?php echo $article->Url; ?> | 永久链接 | | 文章缩略图 | <?php echo $article->Image; ?> | 若未设置则返回空 | | 显示分类名 | <?php echo $article->Category->Name; ?> | 需在循环内调用 | | 文章发布时间 | <?php echo $article->Time('Y-m-d'); ?> | 格式化日期 | | 上一篇/下一篇 | <a href="<?php echo $article->Prev->Url; ?>"><?php echo $article->Prev->Title; ?></a> | 用于 post.php |

注意：在 post.php 中，变量直接用 $article 即可，无需循环，但在 index.php 中必须包裹在 foreach ($articles as $article) 内。

多语言与响应式适配的“坑”

老周的客户要求做一个中英双语主题,且手机端要正常，他按以下步骤解决。

多语言方案：

使用语言包 录下建 /language/ 文件夹，放入 zh-cn.php 和 en.php格式：
```
return array(
    'msg_hello' => '你好',
);
```
然后在模板中调用：
```
<?php echo $zbp->lang['msg_hello']; ?>
```

切换语言
在 header.php 中添加：

<?php if ($zbp->Config('system')->LANG == 'en') { /* 英文版块 */ } ?>

响应式处理：

在 header.php 加入：

<meta name="viewport" content="width=device-width, initial-scale=1">

CSS 使用媒体查询：

@media (max-width: 768px) {
    .sidebar { display: none; } /* 手机端隐藏侧边栏 */
}

如果某些模板标签输出固定宽度（如文章列表的图片），用 max-width:100% 强制自适应：
```
.post-image img { max-width: 100%; height: auto; }
```

最后提醒：每次修改完 include.php 或模板文件，务必到后台“清空缓存”，否则大概率“改了没反应”，如果你还有疑问，先看 zb_users/cache/ 日志，里面有玄机。

正文

ZBlog应用中心开发者规范，从主题调试到插件排错的实战手册

主题安装后首页空白，怎么排查？

侧边栏模块怎么按自己的顺序排？

插件安装后功能不生效？三步排查法

主题模板文件怎么改才安全？

常用模板标签调用速查

多语言与响应式适配的“坑”

相关阅读

ZBlog应用中心开发规范，从实战问题到解决方案

发表评论取消回复

目录[+]