如何启用 WordPress 调试模式以查找和修复错误

WordPress 显示白屏、500 错误或插件表现异常 — 但您不知道原因？调试模式是 WordPress 的内置工具，它揭示隐藏的 PHP 错误，让您能够精确高效地解决问题。

本指南涵盖 WordPress 中所有可用的调试常量 — WP_DEBUG、WP_DEBUG_LOG、SCRIPT_DEBUG — 以及 Query Monitor 等免费工具，并警告在实时生产服务器上不应该做什么。

1. WordPress 调试模式是什么？

默认情况下，WordPress 会抑制所有 PHP 错误、警告和通知。访客只会看到白屏或"发生了严重错误"，而不知道真正的原因。

调试模式是 wp-config.php 中的一组常量，它告诉 WordPress：

• 在屏幕上显示 PHP 错误、警告和通知（或将其写入日志文件）
• 以非压缩形式加载 JavaScript 和 CSS，便于调试
• 记录每个数据库查询以进行性能分析

2. 在 wp-config.php 中启用 WP_DEBUG

文件 wp-config.php 位于您的 WordPress 根目录（与 wp-admin 和 wp-content 同一文件夹）。您可以通过 DirectAdmin 的文件管理器或 FTP 进行编辑。

在 wp-config.php 中找到这一行：

define( 'WP_DEBUG', false );

用适当的配置替换它：

// 启用调试模式
define( 'WP_DEBUG', true );

// 将错误写入日志文件（建议用于生产环境）
define( 'WP_DEBUG_LOG', true );

// 从屏幕隐藏错误（对实时站点更安全）
define( 'WP_DEBUG_DISPLAY', false );

// 加载未压缩的 JS/CSS 文件
define( 'SCRIPT_DEBUG', true );

3. WP_DEBUG_LOG 与 WP_DEBUG_DISPLAY

这两个常量的用途不同 — 根据您的情况选择正确的组合：

对于生产服务器：使用 WP_DEBUG_LOG = true 与 WP_DEBUG_DISPLAY = false 组合，以便安静地捕获错误，而不向访客暴露。

4. SCRIPT_DEBUG 用于 JavaScript

SCRIPT_DEBUG 强制 WordPress 加载完整的、未压缩的 JavaScript 和 CSS 文件版本，而不是压缩包，这样可以更容易地在浏览器 DevTools 中读取和调试代码。

define( 'SCRIPT_DEBUG', true );

在以下情况下使用此常量：

• JavaScript 表现异常，您需要阅读原始源代码
• 您想知道哪个插件或主题加载了特定脚本
• 在浏览器 DevTools 中调试 JavaScript 错误

5. 从 debug.log 读取错误日志

设置 WP_DEBUG_LOG = true 后，WordPress 会自动在 /wp-content/debug.log 处创建日志文件。

如何读取 debug.log：

1. 在 DirectAdmin 中打开文件管理器
2. 导航到 public_html/wp-content/
3. 右键单击 debug.log → 查看或编辑
4. 滚动到底部 — 最新的错误出现在文件末尾

常见错误示例

[16-May-2026 10:30:45 UTC] PHP Fatal error: Uncaught Error: Call to undefined function
  plugin_function() in /home/user/public_html/wp-content/plugins/myplugin/functions.php:42

[16-May-2026 10:30:46 UTC] PHP Warning: include(/wp-content/themes/mytheme/missing-file.php):
  Failed to open stream: No such file or directory in /home/user/public_html/wp-settings.php:500

第一个错误指出插件调用了未定义的函数。第二个显示主题尝试包含不存在的文件。两者都告诉您确切要查找的位置。

5b. 解释 debug.log 中的常见错误类型

记录到 debug.log 的错误分为几个类别，每个类别指向不同的根本原因和修复方法。此参考表可帮助您快速分类问题：

示例：读取堆栈跟踪

堆栈跟踪显示导致错误的函数调用序列。从下往上读取 — 底部行是链开始的地方，顶部行是实际发生错误的地方：

PHP Fatal error: Maximum execution time of 30 seconds exceeded
  in /home/user/public_html/wp-includes/class-http.php on line 423
  Stack trace:
  #0 /wp-content/plugins/myplugin/import.php(88): WP_Http->request()
  #1 /wp-includes/cron.php(467): myplugin_import_data()
  #2 {main}
  thrown in /wp-includes/class-http.php on line 423

此跟踪显示 myplugin 中的 cron 作业触发了超过 30 秒限制的 HTTP 请求。修复方式是增加 PHP 设置中的 max_execution_time，或将导入分解为较小的批次。

6. Query Monitor 插件

Query Monitor 是一个免费开发者插件，在 WordPress 管理栏中显示实时调试信息面板 — 无需编辑任何文件。

Query Monitor 显示的内容：

• 数据库查询 — 每个 SQL 查询、执行时间以及触发它的插件或主题
• PHP 错误 — 所有错误类型在清晰可见的红色面板中显示
• 钩子 & 操作 — 在当前页面上执行的所有操作和过滤器
• 脚本 & 样式 — 所有加载的 JavaScript 和 CSS 文件及其源
• HTTP API 调用 — 页面加载期间进行的所有外部 API 请求
• 重写规则 — 帮助调试永久链接和 404 问题

6b. 其他值得安装的调试工具

除了 Query Monitor，还有几个其他工具可以帮助更有效地诊断特定的 WordPress 问题：

Kint 调试器

Kint 是一个 PHP 调试库，在浏览器中将变量、数组和对象呈现为干净、交互式的可折叠树 — 远比 var_dump() 可读。在主题的 functions.php 中使用它：

d($wpdb->queries); // 显示所有数据库查询
dd(get_queried_object()); // 显示并停止执行

健康检查 & 故障排除（WordPress 官方）

WordPress.org 的这个官方插件包括一个故障排除模式，禁用所有插件并切换到默认主题 — 但仅对已登录的管理员有效。普通访客继续正常看到网站。这使得可以安全地识别实时站点上的插件冲突，无需停机。

WP Crontrol

帮助调试未运行的 WordPress cron 作业。它列出所有计划的 cron 事件，显示下次运行时间，并允许您手动触发任何事件以测试其是否正确执行 — 当 WP_DEBUG_LOG 显示与 cron 相关的错误时很有用。

无需逐个停用即可找到有问题的插件

插件冲突是 WordPress 错误最常见的来源之一。当多个插件相互作用时，组合可能产生任何单个插件单独无法产生的行为。以下是两种有效的隔离方法：

方法 1：健康检查故障排除模式

从 WordPress.org 安装官方的健康检查 & 故障排除插件，并激活故障排除模式。这会临时禁用所有插件 — 但仅对已登录的管理员有效。普通访客正常看到网站。逐个启用插件，直到问题再次出现。您重新启用的最后一个插件就是冲突来源。

方法 2：二进制搜索（平分法）

对于有许多插件的网站，二进制搜索比逐个测试快得多：

1. 禁用您的活跃插件中的一半
2. 如果问题消失 — 罪魁祸首在禁用的组中
3. 如果问题仍然存在 — 罪魁祸首在仍然活跃的组中
4. 对可疑的一半重复，直到只剩一个插件

7. 调试栏插件

调试栏在 WordPress 管理栏中添加了一个"调试"菜单，包含以下面板：

• PHP 信息（版本、加载的扩展）
• 查询详情（总数、执行时间）
• 对象缓存统计（命中/未命中）
• 请求信息（GET/POST 数据、服务器变量）

调试栏支持额外的扩展，包括调试栏控制台，允许您直接从浏览器面板运行 PHP 代码。

7b. 使用 DirectAdmin 在 AsiaGB 主机上调试 WordPress

AsiaGB 主机使用 DirectAdmin 作为其控制面板，提供多个内置工具，使 WordPress 调试变得简单直接，无需 SSH 访问。

通过文件管理器编辑 wp-config.php

1. 在 yourdomain.com:2222 登录 DirectAdmin
2. 点击文件 → 文件管理器
3. 导航到 public_html/（或 WordPress 安装的位置）
4. 右键单击 wp-config.php → 编辑
5. 添加您的调试常量 → 点击保存

直接在 DirectAdmin 中查看 PHP 错误日志

DirectAdmin 包含内置的错误日志查看器，因此您无需手动通过文件管理器导航：

1. 在 DirectAdmin 中，转到高级功能 → 错误日志
2. 选择您要检查的域
3. 最近的 PHP 错误将立即显示，无需打开 debug.log

错误提示兼容性问题时更改 PHP 版本

如果 debug.log 显示有关不存在或已弃用的函数的错误，可能存在 PHP 版本不匹配的问题。DirectAdmin 的 PHP 选择器可让您立即在 PHP 版本之间切换 — 无需重启服务器。对于 WordPress 6.x，建议使用 PHP 8.1 或 8.2。

8. 修复问题后关闭调试模式

一旦您识别并修复了问题，立即禁用调试模式 — 特别是在生产服务器上。

// 禁用调试模式（默认状态）
define( 'WP_DEBUG', false );

// 安全替代方案：保持记录但从屏幕隐藏
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

还要在解决问题后删除 debug.log 文件 — 它可能包含服务器路径或不应该保持可访问的部分凭证信息。

用于更好调试的高级 wp-config.php 常量

除了核心调试常量，wp-config.php 中的几个额外设置可改善调试能力和网站稳定性。以下是按环境组织的最有用的常量：

本地开发 — 完整调试配置

// === 调试（本地开发）===
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true ); // 将每个数据库查询记录到 $wpdb->queries

// === 内存 ===
define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

// === 修订控制 ===
define( 'WP_POST_REVISIONS', 5 ); // 限制修订以防止数据库膨胀

生产环境 — 静默日志配置

// === 调试（生产环境）===
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // 安静地记录错误
define( 'WP_DEBUG_DISPLAY', false ); // 永远不要在屏幕上显示错误
define( 'SCRIPT_DEBUG', false );
// SAVEQUERIES 在生产环境上应为 false — 性能影响显著

// === 安全强化 ===
define( 'DISALLOW_FILE_EDIT', true );  // 禁用管理员中的主题/插件编辑器

9. 按环境推荐的设置