跳过导航,直接阅读主要内容
UTHEME Logo

通过错误日志快速定位WordPress故障

阅读需要 8 分钟

通过 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 错误日志

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 版本不兼容。

  1. 打开日志,跳到文件末尾,找最近时间戳的 Fatal / Parse 行。
  2. 记下完整路径和行号,确认是插件目录还是主题目录。
  3. 通过 FTP 临时重命名该插件/主题文件夹(加后缀 -disabled),再刷新页面验证是否恢复。
  4. 能进后台后,逐个启用并复测,定位真正冲突项;必要时换兼容版本或联系作者。
  5. 若日志为空却仍报错,检查服务器 PHP error.log(主机面板或 phpinfo 可查路径),可能是 WordPress 错误处理启动前就失败了。

想看更具体的白屏与插件冲突案例,可阅读本站文章 WordPress错误日志怎么看:定位白屏和插件冲突。WooCommerce 店铺还可额外到 WooCommerce → Status → Logs 查看商城自身日志,两者结合更高效。

WordPress 官方 Debugging in WordPress 文档页面
WordPress 官方 Debugging in WordPress 文档页面(截图来源:developer.wordpress.org)

打不开后台时如何用日志和恢复模式

自 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 或恢复模式隔离插件主题,就能快速定位大多数白屏和冲突。排查结束后务必关闭调试并删除日志。建议先在预发环境演练一遍,再在生产站点短时启用;同时把性能与错误排查纳入同一维护节奏,需要系统检查时可从本站知识库和加速页面入手。

咨询我们