调试 PHP 代码是任何项目的一部分。WordPress 提供了专门的调试机制，既简化调试过程，也让核心、插件和主题中的代码采用一致的规范。本页介绍 WordPress 提供的各种调试工具，以及如何提高编码效率、代码整体质量和互操作性。

即使你不是程序员，或者只是普通用户，也可以使用这些选项显示详细的错误信息。

注意：修改网站之前，请确认正在使用预发布环境，或者已经为网站做好适当的备份。

用于调试的 wp-config.php 示例

将以下代码插入 wp-config.php 文件后，所有错误、提示和警告都会记录到 wp-content 目录下名为 debug.log 的文件中。同时，错误不会显示在页面上，因而不会打断页面生成。

// Enable WP_DEBUG mode
define( 'WP_DEBUG', true );

// Enable Debug logging to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );

// Disable display of errors and warnings
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Use dev versions of core JS and CSS files (only needed if you are modifying these core files)
define( 'SCRIPT_DEBUG', true );

注意：必须把这些代码放在 wp-config.php 文件中的 /* That's all, stop editing! Happy blogging. */ 之前。

WP_DEBUG

WP_DEBUG 是一个 PHP 常量，即永久性的全局变量，用来开启整个 WordPress 的调试模式。它默认视为 false；在用于开发的 WordPress 副本中，通常会在 wp-config.php 里将其设为 true。

// This enables debugging.
define( 'WP_DEBUG', true );

// This disables debugging.  
define( 'WP_DEBUG', false );

注意：示例中的 true 和 false 没有单引号，因为它们是布尔值。如果把常量设为 'false'，它会被解释为真：引号使它成为字符串，而不是布尔值。

不建议在正式运行的网站上使用 WP_DEBUG 或其他调试工具；这些工具面向本地测试和预发布安装环境。

PHP 错误、警告与提示

启用 WP_DEBUG 后，所有 PHP 错误、提示和警告都会显示。这通常会改变 PHP 的默认行为：默认情况下，PHP 可能仅显示致命错误，或者在出错时显示一片空白。

显示全部 PHP 提示和警告后，一些看似运行正常、但没有遵循 PHP 数据校验规范的代码也可能产生错误信息。找到相关代码后，这些警告通常很容易修复；修复后的代码几乎总能更好地抵御缺陷，也更容易维护。

自定义 PHP 调试

如果调试时需要记录并非错误的信息，可以使用 PHP 的 error_log 函数。不过，它默认不会提供格式良好的输出。

为解决这个问题，可以创建自定义插件，或者通过代码片段插件加入一个负责格式化的函数。这个函数包装 error_log，先用 print_r 正确格式化数组和对象，再写入日志。 （custom plugin） （code snippets）

以下示例函数要求先启用 WP_DEBUG。

function write_log( $data ) {
    if ( true === WP_DEBUG ) {
        if ( is_array( $data ) || is_object( $data ) ) {
            error_log( print_r( $data, true ) );
        } else {
            error_log( $data );
        }
    }
}

使用示例：

write_log( 'DEBUG TEXT' );
write_log( $variable );

注意：不建议把上述示例一类的自定义代码加进 functions.php，以免产生维护、安全、性能、兼容性和代码组织方面的问题。

已弃用的函数和参数

启用 WP_DEBUG 后，还会提示网站正在使用的 WordPress 已弃用函数和参数。这些函数或参数尚未从核心代码中移除，但已计划在未来删除。弃用提示通常会指出应当改用的新函数。

WP_DEBUG_LOG

WP_DEBUG_LOG 与 WP_DEBUG 配合使用，会把所有错误同时保存到 debug.log 日志文件中。如果需要稍后检查全部提示，或者查看没有显示在页面上的提示，例如 AJAX 请求或 wp-cron 运行期间产生的提示，这个功能很有用。

这样也可以使用 PHP 内置的 error_log() 函数写入日志文件，例如调试 Ajax 事件时就很方便。

设为 true 时，日志会保存到网站文件系统的内容目录中，通常为 wp-content/debug.log。也可以将它设为一个有效的文件路径，把日志保存到其他位置。

define( 'WP_DEBUG_LOG', true );

或者：

define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

注意：只有 WP_DEBUG 已启用，即值为 true，WP_DEBUG_LOG 才会生效。WP_DEBUG_DISPLAY 可以单独关闭。

WP_DEBUG_DISPLAY

WP_DEBUG_DISPLAY 也与 WP_DEBUG 配合使用，用来控制是否在页面 HTML 中显示调试消息。默认值为 true，错误和警告一旦产生就会显示；设为 false 则会隐藏全部错误。建议配合 WP_DEBUG_LOG 使用，以便稍后查看错误。

define( 'WP_DEBUG_DISPLAY', false );

注意：只有 WP_DEBUG 已启用，即值为 true，WP_DEBUG_DISPLAY 才会生效。WP_DEBUG_LOG 可以独立控制。

SCRIPT_DEBUG

SCRIPT_DEBUG 是一个相关常量，它会强制 WordPress 使用核心 CSS 和 JavaScript 文件的开发版本，而不是通常加载的压缩版本。测试内置 .js 或 .css 文件的修改时，这个选项很有用。默认值为 false。

define( 'SCRIPT_DEBUG', true );

SAVEQUERIES

定义 SAVEQUERIES 后，数据库查询会保存到一个数组中，可将其显示出来辅助分析。这个常量设为 true 时，每条查询都会与执行耗时及调用它的函数一同保存。

define( 'SAVEQUERIES', true );

该数组存储在全局变量 $wpdb->queries 中。

注意：此选项会影响网站性能，不再调试时务必关闭。

调试插件

WordPress 有许多调试插件，可以提供某个具体组件或者整体内部运行情况的更多信息。 （debugging plugins）

例如，Debug Bar 会在管理工具栏加入调试菜单，显示查询、缓存以及其他有用的调试信息。启用 WP_DEBUG 后，它还会跟踪 PHP 警告和提示，使这些信息更容易找到。

自动化测试与单步调试

日志和调试插件有助于发现运行时错误；另一些问题则更适合使用自动化测试或单步调试器调查。

WordPress 开发使用 PHPUnit 进行 PHP 自动化测试。测试可以帮助确认代码符合预期，也能防止同一个缺陷再次出现。对于插件项目，可以用 WP-CLI 生成插件测试文件的基础结构。 （WP-CLI can scaffold plugin test files）

Xdebug 是一个 PHP 扩展，可以配合兼容的编辑器或 IDE 进行单步调试。它允许在代码运行时暂停、检查变量并跟踪调用栈。当日志消息缺乏足够上下文、难以解释问题时，这些能力尤其有用。

应当在本地开发或预发布环境中使用这些工具，不要直接用于生产网站。