主题安装后首页白屏——从日志到模板的逆向排查
当你满心欢喜上传一套新主题，点击“启用”后刷新首页，看到的却是空白页面或“404 Not Found”，别急着怀疑主题损坏,先执行以下标准流程：
第一步：开启调试模式
在 zb_users/c_option.php 中找到 ZC_DEBUG_MODE 并设为 true,同时添加：
define('ZC_DEBUG_MODE', true);
define('ZC_DEBUG_MODE_WARNING', true);
刷新首页，错误会直接输出，常见的错误提示是 PHP Fatal error: Uncaught Error: Call to undefined function...,这通常是因为模板中调用了未注册的函数。
从主题调试到全站优化，ZBlog应用中心开发者模块深度实战指南
第二步：检查模板入口文件 录下的 template.php，查看最上方是否有 # Ajax 模式也要用的关键函数 注释块,确保有以下代码：
RegisterPlugin('你的主题ID', 'Activate', '你的激活函数');
如果缺少激活函数,会导致应用中心无法正确加载主题依赖的插件模块。
function MyTheme_Activate() {
global $zbp;
// 注册侧边栏挂载点
$zbp->modulesbyfunction['menu'] = 'MyTheme_MenuModule';
}
第三步：模板标签兼容性测试
在 template.php 的 Response() 函数内,先用最简化的代码测试：
function Response() {
global $zbp;
echo '<!-- Test Output -->';
return;
}
如果能正常显示“Test Output”，说明是模板标签调用问题，此时逐步恢复 include 语句，定位到具体是哪一行导致崩溃，常见坑点：部分老主题仍使用 $article->Metas->xxx 这种已废弃的元数据调用方式，需改为 $article->Metas('xxx')。
侧边栏模块神秘失踪——排序与调用的三权分立
ZBlog 的侧边栏模块由“系统模块”、“用户自定义模块”和“主题注册模块”三层构成，当你发现某个模块不显示时,按以下链条排查：
模块注册是否成功？
在主题的 Activate 函数中加入以下代码,确认模块已被写入数据库：
$zbp->modulesbyfunction['mymodule'] = 'MyModule_Func'; // 强制刷新模块缓存 $zbp->BuildModuleCache();
然后在后台“模块管理”中查看是否出现名为 mymodule 的模块，若没有，检查 MyModule_Func 函数是否在 include.php 内定义,且函数名拼写完全一致。
排序权重被覆盖
ZBlog 的模块排序由 Order 字段控制（数值越小越靠前），但主题的 template.php 中 echo $modules['sidebar']; 的输出顺序受 $zbp->option['ZC_SIDEBAR_ORDER'] 影响，默认值“1”代表按自定义排序，改为“0”则按模块ID排序，若你是按ID顺序注册的模块，但希望按特定顺序显示，可在 Activate 中显式写入：
$zbp->option['ZC_SIDEBAR_ORDER'] = '1'; // 开启自定义排序 // 设置每个模块的Order值 $module = $zbp->GetModuleByID(5); $module->Order = 10; $module->Save();
模板直接硬编码调用
部分开发者会在 template.php 中写死：
<div id="sidebar">
<?php echo $modules['catelog']; ?>
</div>
这种方法会绕过模块管理系统，导致后台排序无效，正确做法是遍历 $modules['sidebar'] 数组（注意：这个数组已经按 Order 排序好了）：
foreach ($modules['sidebar'] as $key => $module) {
echo $module; // 模块内容已由系统自动渲染
}
插件安装后功能失效——从激活到钩子的死循环排查
你安装了一个“文章目录插件”，但文章页未显示任何目录,这通常是钩子注册时机或优先级问题。
步骤1：验证插件是否成功激活
在 zb_users/plugin/你的插件ID/main.php 开头添加：
if (function_exists('Add_Filter_Plugin')) {
Add_Filter_Plugin('Filter_Plugin_ViewPost_Template', '你的函数名');
}
注意：ZBlog 1.7+ 版本要求在 InstallPlugin 函数内注册钩子，否则重启应用中心后钩子会丢失,正确的激活函数示例：
function YourPlugin_Install() {
global $zbp;
$zbp->AddAction('Filter_Plugin_ViewPost_Template', 'YourPlugin_AddTOC');
}
步骤2：钩子执行优先级试探
在 main.php 的钩子函数中，先用 file_put_contents 写入日志：
function YourPlugin_AddTOC(&$template) {
file_put_contents('zb_users/cache/test.log', date('Y-m-d H:i:s')."\n", FILE_APPEND);
// 确保函数被执行
}
刷新文章页后检查 test.log，若没有新记录，说明钩子未被触发，常见原因：插件ID与另一个插件冲突（检测 zbp->activeapps 数组），或主题的 template.php 中强行 exit; 跳过了钩子执行。
步骤3：检查插件输出是否被模板覆盖
若钩子触发了但页面无变化，查看主题的 post-single.php 是否在 $template->output(); 之后额外调用了 echo 清空了输出缓冲区，解决办法：在钩子函数中使用 ob_start() 捕获输出，并在最后 echo ob_get_clean();。
模板文件修改后不生效——缓存与路径的障眼法
当你修改了 include.php 或 style.css 但刷新无变化时,先清理这三层缓存：
// 1. 模板编译缓存（ZBlog 1.7+ 特有）
$zbp->ClearCompiledTemplate();
// 2. 应用中心缓存
$zbp->Remove('cache/apps_您的主题ID');
// 3. 浏览器缓存（在模板头部添加版本号）
<link rel="stylesheet" href="{$host}zb_users/theme/你的主题ID/style.css?v={$zbp->version}" />
特别提醒：如果你修改的是 template.php 中的PHP代码，必须去后台“主题管理”里重新启用一次该主题,因为ZBlog会在启用时重新编译模板文件。
常用模板标签的“最小调用集”
文章列表页获取带缩略图的文章
{foreach $articles as $article}
<div class="post">
<h2><a href="{$article->Url}">{$article->Title}</a></h2>
<img src="{$article->Intro|get_thumbnail:'400x300'}" alt="{$article->Title}" />
<p>{$article->Intro|substr:0:100}</p>
<span>{$article->Time('Y-m-d')}</span>
</div>
{/foreach}
注意：get_thumbnail 是自定义函数，需在 include.php 中定义：
function get_thumbnail($intro, $size) {
preg_match('/<img.*?src="(.*?)"/', $intro, $match);
return $match[1] ?? 'default.jpg';
}
分类列表的层级嵌套
ZBlog 的分类数据是扁平的,需手动构建树结构：
$categories = $zbp->GetCategoryList();
function buildTree($items, $parentId = 0) {
$tree = [];
foreach ($items as $item) {
if ($item->ParentID == $parentId) {
$item->children = buildTree($items, $item->ID);
$tree[] = $item;
}
}
return $tree;
}
$tree = buildTree($categories);
自定义字段的兼容调用
在ZBlog 1.7+ 中，$article->Metas('myfield') 返回字符串，但若字段不存在会返回 null，必须用 默认值：
{$article->Metas('price') ?? '未设置'}
多语言与响应式的双重适配陷阱
语言适配：不要硬编码语言标识
在主题的 language 文件夹中创建 zh-cn.php 和 en.php,然后在模板中使用：
{$lang['msg']['read_more']} // 对应语言文件中的 $lang['msg']['read_more'] = 'Read More'
注意：语言文件的加载时机在 template.php 的 Response() 函数之前，所以在 include.php 中需使用全局变量 $GLOBALS['lang']。
响应式：CSS与PHP的边界
避免在PHP中判断设备类型，而是用CSS媒体查询，但有些场景（如移动端隐藏侧边栏）需在PHP层面处理：
// 在 template.php 中检测移动端
$isMobile = false;
if (strpos($_SERVER['HTTP_USER_AGENT'], 'Mobile') !== false) {
$isMobile = true;
}
// 在侧边栏输出时
if (!$isMobile) {
echo $modules['sidebar'];
}
更优雅的做法是注册一个全局变量 $GLOBALS['theme_config']['sidebar_hidden'] = $isMobile;，然后在CSS中通过 [data-sidebar-hidden="true"] 属性控制显示。
一个隐藏的坑：当主题同时包含多语言和响应式时，语言切换会导致响应式布局重置。 解决方案是在 include.php 的 Active 函数中，将语言设置写入 $_SESSION['language']，然后在模板头部用JavaScript保持 data-lang 属性不变：
// 在 footer.php 中
$('html').attr('data-lang', '{$zbp->lang['msg']['lang']}');