WordPress白屏最坑的地方，是它什么都不告诉你。页面一片白，没有报错，没有提示，你连从哪下手都不知道。官方在排障答疑页里把这种情况列进常见错误清单，英文原名 The White Screen，处理方向是先在 wp-config.php 打开 WP_DEBUG 和 WP_DEBUG_LOG，让错误写进 wp-content/debug.log，再按日志指向停用插件、切回默认主题。
对做出海站的人来说，白屏不是页面难看一点的问题。访客进不来，搜索引擎抓不到，前面写的文章和铺的词全停在那儿。真遇上，先把站点的文件结构认清楚，可以照WordPress建站教程走一遍，再回来看这篇。猎者出海做英文独立站，主机、主题、插件都自己装，这类故障也在这套流程里处理。
- 白屏是官方列出的常见错误之一，原名 The White Screen。
- 官方说调试工具用于本地测试和 staging 安装，不推荐在线上站点用。
- 开日志的三行常量要插在 /* That's all, stop editing! Happy blogging. */ 之前。
- 常量值加引号写成 'false'，会被当成 true。
这篇只讲白屏这一件事，每一步都写成能照着做的动作，卡住了也有回查的位置。
本文目录
白屏到底是什么：官方为什么把它列进常见错误
官方原句里的 The White Screen 指什么
官方排障答疑页把用户最常遇到的 WordPress 错误列了一份清单，白屏是其中一项，原文写的是「The White Screen」。同一份清单里还有内部服务器错误、数据库连接错误这些，白屏和它们排在一起，说明官方把它当成一类独立的故障表现，不是某条报错的别名。
这一页给的是方向，不是一条一条对着修的清单。先确认是白屏这一类，再按调试日志和停用插件这两条路往下走。
PHP 默认只显示致命错误，所以出错就是白屏
PHP 的默认显示行为是只显示致命错误，其他级别的错误和警告不往页面上打。站点一旦出错，浏览器收到的就是一个空页面，你打开网页什么也看不见。
官方调试文档讲的正是这件事：默认行为只显示致命错误，出错时就表现为白屏。错误发生了，线索被显示设置挡住了，不开日志就没有任何东西可看。所以排查的第一步不是去猜哪个插件有问题，是先把日志开起来。
WordPress 5.2 起有 Recovery Mode，插件致命错误不再白屏
WordPress 5.2 引入了 Recovery Mode。插件引起致命错误时，它会显示错误信息，不再给一片白，用户那边也不会直接看到白屏和 PHP 报错。官方这句限定的场景是插件导致的致命错误，别把它当成所有白屏都不会出现了。
还有一条和调试显示有关：在开发环境里想让 WP_DEBUG_DISPLAY 真的把错误打到页面上，得先把 WP_DISABLE_FATAL_ERROR_HANDLER 设为 true，把 Recovery Mode 关掉，否则页面还是走 Recovery Mode 那一套。这一条只在本地或 staging 上有意义，线上别动。
WordPress启用插件后500错误讲的是同一个方向上的另一种表现，排查工具和入口是同一批。
动手前先做两件事：备份，和把调试开在 staging
改动前先确认 staging 或合适备份
官方调试文档开头有一条提醒：动网站之前，先确认你用的是 staging 环境，或者已经给站点做了合适的备份。这句话放在整篇文档最前面，意思是后面的每一步都可能把站点弄坏，先给自己留一条能退回来的路。
备份要能拿回来才算数。只导出数据库不够，wp-content 里的插件、主题、上传文件也得在。官方在服务器文档里同样写了，改文件或者动数据库之前要创建当前备份，服务器设置改错会让站点直接不可用。
官方不推荐在线上站点用 WP_DEBUG
官方写得很明确：不建议在线上站点使用 WP_DEBUG 或其他调试工具，它们是为本地测试和 staging 安装准备的。调试模式会把错误、警告、通知显示在页面 HTML 里，访客看到的是报错，站点看起来就是坏的。
正规做法是先在 staging 上把三行常量开起来，把白屏复现出来，确认问题落在哪个组件，再回线上处理。手上没有 staging 的主机，就用一份站点备份在本地搭一个，线上要改什么，先在本地走一遍。
用托管主机时先查主机文档或支持渠道
官方在服务器文档里写明，用托管主机的话，改服务器配置之前先查主机自己的文档或支持渠道。主机商会锁掉一部分权限，也会有自己的缓存和错误日志入口，按通用教程硬改，容易改到一个不生效的地方，白改一场。
自己管服务器的话，官方建议尽量在 staging 里测试改动，并且记下原始配置，改动没按预期生效时可以恢复。记原始配置这一步别省，出问题时你连改回哪里都不知道。
按顺序排查：从开日志到定位到具体插件
下面这五步来自官方调试文档、排障答疑页和主题文档，一步一步做下来，最后落到具体是哪个插件或者哪个主题。
- 开日志，在 wp-config.php 插三行常量。这个文件在 WordPress 文件目录的根部，装着数据库连接这类基础配置，用主机文件管理器或 FTP 打开它。官方示例的作用是把所有错误、通知和警告记进 wp-content 目录下的 debug.log，同时把错误隐藏掉，不让它打断页面生成。片段照原样写：
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
实操截图：改名 plugins.hold 等于停用全部插件，设置仍保留。 true 和 false 是布尔值，不加引号。三行必须插在 /* That's all, stop editing! Happy blogging. */ 之前，插在它之后不生效。回查的时候先看 WP_DEBUG 是不是真的设成了 true，另外两行都要靠它才起作用，WP_DEBUG_LOG 没生效，debug.log 根本不会生成。
- 打开 debug.log 看最新报错。WP_DEBUG_LOG 设成 true 时，日志写在内容目录下的 debug.log，位置通常是 wp-content/debug.log；也可以把它设成一个有效文件路径，把日志存到别处。这个日志的用处是看屏幕外产生的通知，比如 AJAX 请求或者 wp-cron 运行期间产生的那些，页面上根本看不到。打开或下载以后直接翻到最后，看最新几条指向哪个插件目录、哪个主题文件、哪个函数名。日志是空的，就再刷新一次白屏页，然后重新取一次文件。
- 进不了后台，就把 plugins 改名。官方答疑页给了两种停用全部插件的办法，其中一种是进 wp-content，用 FTP 或文件管理器把 plugins 文件夹改名成 plugins.hold，插件设置会保留。改完打开 /wp-admin/plugins.php，WordPress 会提示插件缺失，等于已经全部停用。能登录以后再把文件夹改回 plugins，插件还是停用状态，这时候一个一个重新启用，启用哪个白屏就锁定哪个。另一种办法是用 phpMyAdmin 把 wp_options 表里 active_plugins 那行的 option_value 改成 a:0:{}，不熟悉这个工具就找主机商或者开发者帮忙。
- 能进后台，先切默认主题，预览空白的新主题别直接启用。官方主题文档写得很直接：主题预览是空白的时候，不要不做调查就启用新主题。看不到缩略图，说明新主题可能已经损坏，先联系主题作者。操作上先在预览里看一眼，正常了再启用。启用后站点恢复，问题就在原来那个主题上；启用后还是白屏，方向不在主题，回头继续看日志。
- 日志还不够用，再上 step debugger。Xdebug 是 PHP 扩展，配合兼容的编辑器或 IDE 做单步调试，可以暂停正在跑的代码、检查变量、跟踪调用栈。官方说日志消息不足以解释问题时它有帮助。这套工具只在本地或者 staging 上用，不要直接放到生产站点，它也不是白屏排查的第一选择。
服务器这一层要找的文件位置和面板入口，属于主机面板的事，操作可以对照宝塔面板安装教程。
做这件事要用的数字和版本门槛
排查到后面要装工具、上调试器，先对一遍版本。版本不对，工具装上也是白装。
| 项目 | 数值 | 用在哪一步 |
|---|---|---|
| WordPress 推荐的 PHP 版本 | 8.3 或更高 | 第 5 步上 Xdebug 之前对一遍 |
| WordPress 推荐的数据库版本 | MySQL 8.0 / MariaDB 10.11 或更高 | 同上 |
| 当前可下载的 WordPress 版本 | 7.1.4 | 判断站点是不是落后核心更新 |
| Debug Bar 要求 | WordPress 3.4+、PHP 5.4.0+ | 装 Debug Bar 之前对一遍 |
| Debug Bar 版本 / 活跃安装 | 1.2.0 / 2 万以上 | 判断这个工具还在不在被用 |
这几行数字只用来对版本，跟修复要多久没关系。快慢取决于日志指向哪个组件，别先给自己定一个时间表，按步骤走。
Debug Bar 是能装在后台的调试插件，装上会在管理栏加一个调试菜单，显示查询、缓存这些信息，开启 WP_DEBUG 时还会跟踪 PHP 警告和通知。版本和安装量在上表里，装之前对一遍要求，对不上就别装。
五个常见误区，和排查卡住时回查哪里
误区一：常量值加引号写成 'false'，实际等于开启
结论：'false' 不是 false。官方写明，常量值加上引号就变成字符串，会被解释成 true，你以为关掉了显示，实际是开着的。依据是官方对布尔值的那句提醒：true 和 false 不加撇号，因为它们本身就是布尔值。
误区二：在线上站点开调试工具
结论：调试开关开在线上，访客看到的是报错，站点等于在裸奔。依据是官方的明确态度，这些工具是为本地测试和 staging 准备的。线上的问题先在 staging 复现，再回线上处理。
误区三：把调试代码写进 functions.php
结论：调试常量不属于主题文件。官方不建议把这类自定义代码放进 functions.php，理由是维护、安全、性能、兼容和代码组织上的问题。三行常量该待在 wp-config.php 里，换主题不该把它们带走。
误区四：开着 SAVEQUERIES 不关，影响性能
结论：SAVEQUERIES 是临时开关，不是常设配置。官方写明它会对站点性能有影响，不调试的时候要关掉。要看 MySQL 查询的时候开，看完就去掉，别留在 wp-config.php 里。
误区五：主题预览空白仍直接启用新主题
结论：预览空白说明这个主题在你站点上跑不起来。看不到缩略图，主题文件可能已经损坏，先联系主题作者，别抱着试一下的心态启用。
关于「内存不足」：自己去确认，别凭猜测动参数
先看主机的错误日志和 PHP 配置里的当前内存上限，再看 debug.log 里有没有和内存相关的报错行。日志里有具体的报错行，再谈调高；日志里没有这一行，就别凭猜测动内存参数。
排查最后落到插件或主题上时，这两个方向可以对照着看：插件装不上或者装上报错，看插件安装失败；换主题之后站点出问题，看WordPress主题不兼容。
用 AI 帮你定位白屏：哪几步能交、哪几步必须自己动手
AI 在这件事上做的是整理和对照，它打不开你的服务器，也判断不了你的站点恢复没有。能交的活儿和必须自己动手的活儿，分清楚再开始。
AI 能帮的三步
- 归类日志。把 debug.log 里抓到的报错行贴给 AI，让它按插件、主题、核心三类分开，指出最可能出问题的组件名，并要求它说明依据是哪一行。
- 整理配置片段。让 AI 把官方那三行调试常量整理成可以直接粘贴的片段，并标出插入位置在 /* That's all, stop editing! Happy blogging. */ 之前。
- 列排查顺序。把报错里的函数名或插件名交给 AI，让它列出逐个停用插件、切默认主题的顺序清单，每步写清在哪个后台或哪个文件里操作、看什么结果决定下一步。
人必须自己做的三件事
- 在主机文件管理器或 FTP 里打开 wp-config.php，亲手把 WP_DEBUG、WP_DEBUG_LOG、WP_DEBUG_DISPLAY 三行插到 /* That's all, stop editing! Happy blogging. */ 之前并保存。
- 进 wp-content 目录打开或下载 debug.log，看最新几条报错指向哪个插件或哪个主题。
- 在 wp-content 里把 plugins 文件夹改名成 plugins.hold，刷新站点看是否恢复，再决定逐个启用哪个插件。
三条可以照抄的提示词
下面三条是本文给的示例，不是官方模板，按自己的报错改。
「下面是我 WordPress 站点 wp-content/debug.log 里的报错片段，请按插件、主题、核心三类归因，指出最可能的组件，并说明依据是哪一行。报错片段：［粘贴］」
「请把这段官方调试配置整理成可直接粘贴进 wp-config.php 的代码，并注明插入位置在 /* That's all, stop editing! Happy blogging. */ 之前：define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false );」
「我的 WordPress 站点白屏，已开启 WP_DEBUG 和 WP_DEBUG_LOG。请给我一份按顺序执行的排查清单，每步写清在哪个后台或文件里操作、看什么结果决定下一步。」
站点恢复以后，把这次停用了哪个插件、日志里报的什么错记一笔。站点跑起来之后的日常维护是另一回事，猎者出海的AI Agent 做的是上线后自己拉数据、每周给一张改稿单，告诉你改哪几篇、先改哪篇。
常见问题
白屏和500错误是一回事吗
不是。两者都是官方常见错误清单里列出的项目。排查入口是同一批，开日志、停插件、切主题这三步对两种情况都适用。
开了WP_DEBUG还是白屏怎么办
先回 wp-config.php 确认三行常量插在 /* That's all, stop editing! Happy blogging. */ 之前，再看 wp-content 里有没有生成 debug.log。两样都对还是白屏，就把 plugins 文件夹改名成 plugins.hold，看站点有没有恢复。
停用插件后站点恢复了，怎么找出是哪一个
把 plugins.hold 改回 plugins，插件仍然是停用状态。然后一个一个启用，每启用一个刷新一次首页，启用哪个之后白屏回来，问题就在那个插件上。
主题预览是空白的，能直接启用吗
不能。预览空白说明这个主题在你站点上跑不起来，看不到缩略图，主题文件可能已经损坏，先联系主题作者。要试就在 staging 上试，别在线上试。
官方有没有专门讲白屏的页面
官方在排障答疑页的常见错误清单里列了 The White Screen，做法分散在调试文档、排障答疑和主题文档里。把这三处的写法组合起来，就是上面那五步。
不熟悉phpMyAdmin能自己改数据库停插件吗
先走另一条路：用 FTP 或文件管理器把 plugins 文件夹改名成 plugins.hold，效果一样，插件设置还保留。要走改数据库那条也行，官方提醒不熟悉 phpMyAdmin 就找主机商或者开发者协助。
白屏处理完，站点能打开，后面的事还是内容。文章写出来发上去，选题、成稿、本地化这些环节，可以交给猎者出海的AI Agent 的写作编辑过一遍，发之前还有 AI 味检测。
发表评论