WordPress 内置调试选项 – WordPress建站指南

随着你对 WordPress 开发越来越熟练，你会发现有时事情并不像预期那样工作，你需要找出原因。

在本课中，你将了解 WordPress 内置的调试选项。

首先，你将学习调试代码的含义。然后，你将了解默认 WordPress 安装中可用的一些内置调试选项，以及如何启用和使用它们。

什么是调试？

调试是查找并修复代码中错误的过程。

由于 WordPress 的两种主要编程语言是 PHP 和 JavaScript，你需要能够调试这两种语言。

对于在浏览器中执行的 JavaScript 代码，使用 console.log() 向浏览器控制台写入消息以进行测试和调试是相当直接的。

另一方面，PHP 在服务器上执行，因此你需要一些方法来找出问题发生时的情况。

有一些第三方工具可用于高级调试，例如 Xdebug 或 Ray。

然而，就本课而言，你将学习 WordPress 特有的选项，并且不需要额外的软件。

调试 PHP

在 WordPress 中，在任何 WordPress 请求生命周期内，都会运行 wp_debug_mode() 函数来设置调试环境。此函数位于 wp-includes/load.php 文件中。

如果你查看这段代码，你会发现如果 WP_DEBUG 常量设置为 true，那么它会将 PHP 错误报告级别设置为 E_ALL，这意味着开启所有错误报告。

此外，如果 WP_DEBUG_DISPLAY 设置为 true，那么它会将 PHP 的 display_errors 设置设为 1，这意味着在屏幕上显示这些错误。

最后，如果 WP_DEBUG_LOG 设置为 true，那么它会将 PHP 的 error_log 设置设为 wp-content/debug.log 文件。也可以配置自定义的 debug.log 文件位置，而不是默认位置。

如果启用了此日志文件，它会将 PHP 的 log_errors 设置设为 1，并将 error_log 设置设为日志文件的路径，这意味着所有错误都将记录到此文件中。

利用这些知识，你可以配置 wp-config.php 文件来启用 WordPress 调试。

启用调试

要启用调试，请打开 wp-config.php 文件并向下滚动到设置 WP_DEBUG 常量的位置。

你可以将该部分更新为如下所示：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );

此配置将：

启用调试
禁止在屏幕上显示错误
启用将错误记录到 wp-content/debug.log 文件

根据你的个人偏好，你可以启用屏幕上显示错误，但这可能导致错误被忽略或覆盖屏幕上的其他重要内容，这并不理想。

此外，如果你曾经在生产站点上调试问题，你不希望将错误显示在屏幕上，因为这可能导致敏感信息向用户显示。

为了实际查看效果，让我们看一个例子。

假设你开发了一个包含以下代码的插件：

<?php
/**
 * Plugin Name: WP Learn Debugging
 * Plugin Description: A plugin to learn about debugging in WordPress.
 * Plugin URI: https://learn.wordpress.org
 * Version: 1.0.0
 */

/**
 * Set up the required form submissions table
 */
register_activation_hook( __FILE__, 'wp_learn_setup_table' );
function wp_learn_setup_table() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'form_submissions';

    $sql = "CREATE TABLE $table_name (
      id mediumint(9) NOT NULL AUTO_INCREMENT,
      name varchar (100) NOT NULL,
      email varchar (100) NOT NULL,
      PRIMARY KEY  (id)
    )";

    require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
    dbDelta( $sql );
}

/**
 * Register the REST API GET route
 */
add_action( 'init', 'wp_learn_register_routes' );
function wp_learn_register_routes() {
    register_rest_route(
        'wp-learn-form-submissions-api/v1',
        '/form-submissions/',
        array(
            'methods'             => 'GET',
            'callback'            => 'wp_learn_get_form_submissions',
            'permission_callback' => '__return_true'
        )
    );
}

/**
 * Fetch the form submissions for the REST API GET Route
 *
 * @return array|object|stdClass[]|null
 */
function wp_learn_get_form_submissions() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'form_submission';

    $results = $wpdb->get_results( "SELECT * FROM $table_name" );

    return $results;
}

这个插件在激活时会在数据库中创建一个表单提交表，然后注册一个 REST API GET 路由来从数据库中获取表单提交。

出于测试目的，你手动在 form_submissions 表中插入了几条记录。

但是，如果你访问 REST API GET 路由，你看不到任何表单提交，因此你需要开始查找代码中的错误。

只需启用调试，代码中的任何错误都会自动记录到 wp-content/debug.log 文件中。所以如果你查看一下，你会看到一些错误已被记录。

[02-Jun-2023 13:51:41 UTC] PHP Notice:  Function register_rest_route was called <strong>incorrectly</strong>. REST API routes must be registered on the <code>rest_api_init action. Please see Debugging in WordPress for more information. (This message was added in version 5.1.0.) in /home/ubuntu/wp-local-env/sites/learnpress/wp-includes/functions.php on line 5865

在这种情况下，报告了两个错误。首先是由 WordPress 触发的 PHP 通知，这是由于将 wp_learn_register_routes 函数挂载到了错误的操作上。其次是与用于获取表单提交的数据库查询相关的错误。

看起来它查询的是 form_submission 表，而不是 form_submissions 表。

一旦你修复了这些错误，并访问 REST API GET 路由，你就会看到表单提交被返回了。

使用 error_log 进行调试

除了将错误记录到 debug.log 文件之外，你还可以使用 PHP 的 error_log 函数将消息或变量记录到 debug.log 文件。

此函数接受一个字符串参数。

例如，如果你想将正在运行的 SQL 查询记录到 debug.log 文件中，可以使用以下代码：

error_log( $wpdb->last_query );

如果你刷新请求并查看 debug.log 文件，就会看到查询被记录到该文件中。

[02-Jun-2023 13:55:35 UTC] SELECT * FROM wp_form_submissions

使用 SAVEQUERIES 常量

除了记录最后一条查询，你还可以记录 WordPress 请求生命周期中运行的所有查询。

要实现这一点，你可以在 wp-config.php 文件中启用 SAVEQUERIES 常量。

define( 'SAVEQUERIES', true );

启用此常量后，你可以使用以下代码记录所有查询：

error_log( print_r( $wpdb->queries, true ) );

这段代码结合使用了 error_log() 函数和 PHP 的 print_r() 函数，将 $wpdb->queries 数组记录到 debug.log 文件中。

该数组包含了 WordPress 请求生命周期中运行的所有查询，并且仅在启用 SAVEQUERIES 常量时才可用。

进一步阅读

有关 WordPress 调试的更多信息，请查看 WordPress 开发者文档中高级管理区域的“WordPress 调试”部分。