详解 WordPress 白屏死亡（WSOD）

白屏死亡是一个你看不到的 PHP 致命错误。WordPress 在渲染中途遇到无法恢复的错误，PHP 停止运行，而由于生产服务器上关闭了错误显示，页面返回一片空白，而不是打印出原因。修复它几乎从来不需要靠猜：打开调试日志，打开 wp-content/debug.log，读最后一行 fatal。它会指出具体是哪个文件——几乎总是某个插件或主题——而那一行就是修复的全部。

为什么屏幕是空白的

PHP 有一个叫 display_errors 的设置。在开发机上它通常是开着的，所以致命错误会把堆栈跟踪打印到屏幕上。而在真实的主机上它默认是关闭的，因为把文件路径和错误信息泄露给访客是一个安全问题。所以当某处抛出致命错误时——调用了一个已经不存在的函数、一个没有被加载的类、插件更新里的语法错误——PHP 就会终止运行，什么都不返回。你的浏览器渲染出一个空文档。这就是所谓的”白屏”。

从 WordPress 5.2 开始，有一个致命错误处理器（WP_Fatal_Error_Handler）会尝试捕获这些错误。当它起作用时，你看到的不是空白页面，而是”此站点遇到了致命错误”，同时会有一封邮件发送到管理员邮箱，里面往往包含真正的错误信息以及一个进入恢复模式（Recovery Mode）的链接。而一个真正空白的屏幕通常意味着错误在这个处理器能够运行之前就已经触发了：一个解析/语法错误（在编译阶段就被捕获）、一个损坏的 must-use 插件，或者当前主题 functions.php 里的一个致命错误。无论哪种情况，原因都被记录在某个地方。你只需要把”记录”这个开关打开。

按顺序修复

1. 打开日志。 通过 SFTP 编辑 wp-config.php，在 /* That's all, stop editing! */ 这一行上方添加：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

WP_DEBUG_DISPLAY 设为 false 可以让错误不出现在公开页面上，同时 WP_DEBUG_LOG 会把它们写入 wp-content/debug.log。刷新一次出问题的页面，生成一条新的记录。

2. 读最后一行 fatal。 打开 wp-content/debug.log，看最底部：

tail -n 30 wp-content/debug.log

你要找的是这样一行：

[14-Jul-2026 09:12:44 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function wc_get_product() in /var/www/html/wp-content/plugins/some-addon/includes/class-widget.php:88

路径指出了罪魁祸首：plugins/some-addon。这就是你的答案。如果堆栈跟踪很长，或者信息很晦涩（Allowed memory size exhausted、Cannot redeclare、一个你不认识的类名），把它粘贴到我们的错误日志解码器——它会剥离掉噪音，告诉你路径指向的是哪个插件或主题，并解释这个具体错误类型意味着什么。

3. 停用被指出的组件。 你进不了 /wp-admin，所以通过 SFTP 来做。把出问题的插件文件夹重命名，例如 some-addon → some-addon.off。WordPress 无法加载一个找不到的文件夹，于是就停用了这个插件，网站也就恢复了。如果日志指向的是你的主题，就通过重命名当前主题文件夹切换到默认主题——WordPress 会回退到自带的 twentytwentysomething。

4. 如果日志写不出来，那就是 wp-content 不可写，或者错误发生在服务器层面。改为查看主机的 PHP 错误日志：

find . -name "error_log" -newermt "-1 hour"

信息一样，只是换了个文件。cPanel/Apache 环境经常会在站点根目录或出问题的目录里丢一个 error_log。

不要做的事

不要一上来就调高内存限制。 网上被复述最多的建议就是把 WP_MEMORY_LIMIT 提高到 256M 或 512M。只有当日志确实写着 Allowed memory size of N bytes exhausted 时，这才能修好 WSOD。如果错误是 Call to undefined function，再多的内存也没用——你只是随手改了个设置，屏幕依旧是白的。先读日志，然后只有在日志明确说是内存问题时才调高内存。

不要清一下缓存就当作诊断。 白屏是 PHP 在服务器上、在任何 HTML 存在之前就终止了。一个过期的缓存资源不可能造成空白文档。（一个损坏的缓存插件可以——但日志会指出它，这才是关键。）

不要编辑或重装 WordPress 核心。 致命错误几乎从不在 wp-includes 或 wp-admin 里；它在日志指向的插件或主题里。重装核心又慢又有风险，而且是在治一个你还没确认过的症状。

不要盲目地停用所有插件再一个个重新启用。 二分排查能奏效，但那是慢路子。日志一步就告诉你确切的文件夹。只有在完全没有可读错误信息时，才动用”全部关掉”这个方法。

不要在生产环境里一直开着 display_errors。 一旦网站恢复，就删掉那些调试定义（或把 WP_DEBUG 改回 false）。打印给访客的错误信息会暴露你的路径。

还是搞不定？

如果日志指出了某个插件，但停用它并没有让屏幕恢复，那就是第一个致命错误下面还压着第二个——把日志重新打开，读新的最后一行；致命错误是会叠加的。如果信息本身就是那堵墙，把它丢进错误日志解码器，让它替你翻译错误类型和文件路径。白屏只有在日志关着的时候才会一直是个谜。