Z-Blog 后台 500 白屏：从 error_log 到定位到具体行的完整流程

后台点一下保存就白屏，刷新还是白屏，登录页能开但进后台就 500——这是 Z-Blog 最常见的一类故障。浏览器只给你一个「500 Internal Server Error」，真正的原因必须去服务器日志里捞。

下面这套流程我按「先确认是哪一层出错，再看 PHP 报错在哪一行，最后定位到具体代码」的顺序走，每一步都能缩小范围。

第一步：先分清是 PHP 挂了还是 nginx 挂了

打开浏览器开发者工具，看 Network 里那个 500 请求的 Response。

• Response 里有 HTML 内容、有 Z-Blog 的样式残留：PHP 执行到一半 fatal 了，错误在 PHP 层。
• Response 是完全空白的纯文本，或者只有 nginx 的默认错误页：多半是 nginx 配置问题或 PHP-FPM 没起来。
• Response 里是 File not found.：nginx 的 fastcgi_param SCRIPT_FILENAME 配错，或 root 指向了错误目录。

这一步确认完，后面就走不同分支。下面主要讲最常见的 PHP fatal 分支。

第二步：打开 Z-Blog 自己的错误日志

Z-Blog 自带错误日志，路径固定在：

zb_users/logs/

登录成功后到后台「网站设置 → 全局设置」，把「调试模式」和「记录错误日志」都打开，再复现一次故障。日志文件按日期命名，形如 20261019.log，打开看最后几条。

如果日志目录是空的，说明 PHP 的 display_errors 和 log_errors 都没开，错误没被记录。这时要去看 PHP-FPM 的日志。

第三步：查 PHP-FPM 的错误日志

宝塔面板路径通常是：

/www/wwwlogs/php-fpm.log
/www/server/php/74/var/log/php-fpm.log

命令行版（LNMP 一键包）在：

/usr/local/php/var/log/php-fpm.log

搜关键词 PHP Fatal error，会看到类似这样的行：

[19-Oct-2026 15:32:11] WARNING: [pool www] child 12345 said into stderr:
PHP Fatal error:  Uncaught Error: Call to undefined function foo()
in /www/wwwroot/site/zb_users/theme/framehome/include.php:128

关键就是最后那句 in 文件:行号，直接告诉你出错文件和行号。

第四步：php.ini 没开日志时的应急办法

如果 php-fpm.log 里也是空的，临时在站点根目录建一个 phpinfo.php：

<?php phpinfo();

访问它，搜 log_errors 和 error_log 两个值：

• log_errors = Off：改成 On
• error_log 为空：填一个绝对路径，如 /tmp/php_error.log

改完重启 PHP-FPM 再复现，错误就落到你指定的文件里了。排查完记得删掉 phpinfo.php，它会泄露大量服务器信息。

第五步：定位到具体行的三种典型成因

拿到行号之后，打开那个文件看该行代码。Z-Blog 后台 500 的高频成因有三个：

成因一：插件钩子挂了不存在的函数

典型报错：

Call to undefined function PluginName_Foo()

原因通常是 include.php 里写了：

$zbp->AddFilter_Plugin('Filter_Plugin_Admin_Footer', 'PluginName_Foo');

但 PluginName_Foo() 这个函数根本没定义，或者定义在另一个没被 include 的文件里。解决办法：要么补上函数，要么先注释掉这行 AddFilter_Plugin，恢复后台访问后再慢慢补。

成因二：主题模板里调用了未定义变量

典型报错：

Undefined variable: foo（Warning）
Call to a member function on null（Fatal）

后台白屏但前台正常，往往是 theme/framehome/template/admin_*.php 这类后台扩展模板出了问题。先把主题切回默认的 default 试一次：
// zb_users/c_option.php 里改这一行
'ZC_BLOG_THEME' => 'default',
能进后台就说明是主题问题，再逐个排查主题文件。

成因三：PHP 版本不兼容
典型报错：
Parse error: syntax error, unexpected ')'
Z-Blog 1.7.x 在 PHP 7.0 以上都能跑，但插件如果用了 PHP 8 的新语法（如 match、命名参数），在老版本 PHP 上就是 Parse error。查 phpinfo.php 里的 PHP 版本，和插件要求的版本对一下。

实在找不到时：逐插件禁用法
如果日志里啥都没有，用最笨但最有效的办法——逐个禁用插件：

进 zb_users/c_option.php
找到 'ZC_USING_PLUGIN_LIST' => '插件A|插件B|插件C'
把列表清空或只留一个，刷新后台
能进后台就说明被排除的插件里有问题，二分法继续缩小


常见问题

Q1：后台 500 但前台完全正常，是哪里坏了？
多半是后台专属代码出错：插件挂的 Filter_Plugin_Admin_* 钩子、主题的后台模板、UEditor 这类后台插件。前台不加载这些代码，所以不受影响。

Q2：日志里报错的行号是空行/注释行，怎么办？
说明出错点在那一行的「上一表达式」——PHP 报告的行号有时会漂到下一行。往上翻五六行找 -> 或 ( 未被闭合的地方。

Q3：改了代码报错消失了，但过会儿又白屏？
大概率是 Z-Blog 的模板编译缓存。到后台「清空缓存并重新编译模板」，或者手动删掉 zb_users/cache/ 下的所有文件。

Q4：公司服务器不让看日志怎么办？
装一个 AiConsole 插件，它有 read_error_logs 能力，能在后台直接读日志尾部，不需要服务器 SSH。

Q5：Error 500 和 Error 502 / 504 要分开处理吗？
要。500 是 PHP 代码出错；502 是 PHP-FPM 崩溃或 nginx 连不上 PHP-FPM；504 是 PHP 执行超时。502/504 先查 PHP-FPM 进程和 max_execution_time，不是代码问题。