通过错误日志快速定位WordPress故障
通过 WordPress 错误日志可以快速定位白屏、插件冲突和 PHP 致命错误。在 wp-config.php 里临时开启 WP_DEBUG 与 WP_DEBUG_LOG 后,错误会写入 wp-content/debug.log,优先查看…
通过 WordPress 错误日志可以快速定位白屏、插件冲突和 PHP 致命错误。在 wp-config.php 里临时开启 WP_DEBUG 与 WP_DEBUG_LOG 后,错误会写入 wp-content/debug.log,优先查看最新的 Fatal error 或 Parse error 行,文件路径通常直接指向出问题的插件或主题。生产站点只短时启用,用完立刻关闭调试并删除日志文件,避免信息泄露和性能负担。

如何启用 WordPress 错误日志
WordPress 内置调试系统,官方文档建议优先在本地或预发环境使用,生产站点仅临时开启。修改前先备份网站或确认有回滚手段。编辑站点根目录的 wp-config.php,把常量写在“That’s all, stop editing! Happy publishing.”(或类似提示)之前,确保在加载 wp-settings.php 之前生效。
推荐配置如下(true/false 不要加引号):
- define( ‘WP_DEBUG’, true ); —— 主开关,打开后 PHP 会报告错误、警告和弃用通知。
- define( ‘WP_DEBUG_LOG’, true ); —— 把错误写入日志;也可写成自定义绝对路径,例如 ‘/home/user/logs/wp-errors.log’(目录需已存在且可写)。自定义路径从 WordPress 5.1 起支持。
- define( ‘WP_DEBUG_DISPLAY’, false ); —— 不在页面上直接显示错误,避免访客看到敏感信息。
- @ini_set( ‘display_errors’, 0 ); —— 进一步关闭页面显示。
保存后重现一次故障(刷新出问题的页面或操作),日志文件才会生成。也可通过主机面板、WP-CLI 或调试类插件辅助,但核心仍是这几个常量。更完整的调试说明可参考 WordPress 官方 Debugging 文档。日常维护与排查步骤也可对照本站 WordPress / WooCommerce 技术知识库 里的相关文章。
| 常量 | 作用 | 生产环境建议 |
|---|---|---|
| WP_DEBUG | 总开关,开启全部错误报告 | 临时 true,用完改 false |
| WP_DEBUG_LOG | 写入 debug.log 或自定义路径 | 配合使用,自定义路径更安全 |
| WP_DEBUG_DISPLAY | 是否在 HTML 中显示错误 | 务必 false |
| SCRIPT_DEBUG | 强制加载未压缩 JS/CSS | 一般保持 false |
| SAVEQUERIES | 记录数据库查询到 $wpdb->queries | 有性能开销,排查完关闭 |
怎么查看并解读错误日志
用 FTP、SFTP 或主机文件管理器打开 wp-content/debug.log(若自定义了路径则去对应位置)。文件只在首次出错后出现,新记录追加在底部。每条大致格式为:
[日期时间 UTC] PHP 类型: 消息 in /完整路径/文件.php on line 行号
优先处理 Fatal error 和 Parse error,它们会直接导致白屏或“There has been a critical error on this website”。Warning、Notice、Deprecated 通常不中断页面,但长期积累也会拖慢站点。路径里出现 plugins/ 或 themes/ 时,基本可锁定是哪个插件或主题出问题;core 文件则可能是主题函数冲突或 PHP 版本不兼容。
- 打开日志,跳到文件末尾,找最近时间戳的 Fatal / Parse 行。
- 记下完整路径和行号,确认是插件目录还是主题目录。
- 通过 FTP 临时重命名该插件/主题文件夹(加后缀 -disabled),再刷新页面验证是否恢复。
- 能进后台后,逐个启用并复测,定位真正冲突项;必要时换兼容版本或联系作者。
- 若日志为空却仍报错,检查服务器 PHP error.log(主机面板或 phpinfo 可查路径),可能是 WordPress 错误处理启动前就失败了。
想看更具体的白屏与插件冲突案例,可阅读本站文章 WordPress错误日志怎么看:定位白屏和插件冲突。WooCommerce 店铺还可额外到 WooCommerce → Status → Logs 查看商城自身日志,两者结合更高效。

打不开后台时如何用日志和恢复模式
自 WordPress 5.2 起,致命错误会触发恢复模式:系统向管理员邮箱发送带临时登录链接的邮件(可用 RECOVERY_MODE_EMAIL 常量指定地址)。点开链接可进入安全后台,停用问题插件或主题。若邮件没收到,仍可用上面的 FTP 重命名法,再配合错误日志确认。
- 先看管理员邮箱是否有恢复模式通知。
- 同时开启 WP_DEBUG_LOG,复现错误,读最新 Fatal 行。
- 确认是插件后,重命名 plugins 下对应文件夹;是主题则切到默认主题或重命名当前主题文件夹。
- 恢复正常后,逐个排查更新、禁用冲突插件,并检查 PHP 版本是否满足要求(官方推荐 PHP 8.3 或更高,最低仍可用 7.4+ 但已过安全支持期)。
恢复模式细节见 WordPress Recovery Mode 官方说明。若故障同时伴随打开缓慢、后台卡顿,建议一并检查缓存与服务器环境,可参考本站 服务器线路与 WordPress 加速说明。
生产环境使用错误日志要注意什么
默认 debug.log 位于网站可访问目录,存在被公开下载的风险,Site Health 也会提示“日志写到了可能公开的文件”。自定义路径移到 web root 之外,或用服务器规则禁止访问该文件。日志没有自动轮转,长期开启会迅速变大,影响磁盘与性能。
- 只在复现故障的短时间内开启,问题解决后立刻把 WP_DEBUG、WP_DEBUG_LOG 改回 false,并删除 debug.log。
- 日志可能包含绝对路径、数据库信息或用户数据,不要长期留在线上,也不要发给不可信第三方。
- SAVEQUERIES 会占用内存,SCRIPT_DEBUG 会加大前端体积,排查结束后都关掉。
- 共享主机权限有限时,若 wp-content 不可写,日志无法创建,需联系主机调整权限或改用自定义路径。
- 截至 2026 年 11 月,当前稳定版为 WordPress 7.1.4(2026-10-28 安全发布),建议保持更新;调试功能本身对版本无额外硬性要求,但自定义日志路径需 5.1 及以上。
跨境独立站日常更关注速度与稳定性时,可把错误日志排查和性能优化放在同一套流程里,详见本站知识库与加速服务页面。
常见问题
开启了 WP_DEBUG_LOG 却没有生成 debug.log?
常见原因是常量写在了“stop editing”之后、WP_DEBUG 未设为 true、根本没有触发错误、或 wp-content 目录权限不足。把常量移到正确位置,重现一次故障,并确认目录可写;仍无文件则查看服务器 PHP error.log。
日志里全是 Notice 和 Deprecated,要不要全部修?
它们一般不导致白屏,但说明代码过时或插件未适配当前 PHP/WordPress 版本。优先处理 Fatal,再逐步更新主题插件;生产环境不必为每一条 Notice 停站,但应计划升级。
Site Health 一直警告日志文件可能公开怎么办?
把 WP_DEBUG 和 WP_DEBUG_LOG 设为 false,删除现有 debug.log。若必须保留自定义路径日志,确认该路径在网站根目录之外且服务器已禁止 HTTP 访问,警告有时会有假阳性。
错误日志和网站变慢有关系吗?
长期开启调试、SAVEQUERIES 或巨大的 debug.log 都会增加负担。排查完立即关闭,并配合缓存、数据库清理和线路优化,才能同时解决故障与性能问题。
启用 WordPress 错误日志、优先阅读 Fatal 行、用 FTP 或恢复模式隔离插件主题,就能快速定位大多数白屏和冲突。排查结束后务必关闭调试并删除日志。建议先在预发环境演练一遍,再在生产站点短时启用;同时把性能与错误排查纳入同一维护节奏,需要系统检查时可从本站知识库和加速页面入手。