wp_debug_mode()
概述
wp_debug_mode() 函数基于 WordPress 调试设置配置 PHP 错误报告，主要依赖 WP_DEBUG、WP_DEBUG_DISPLAY 和 WP_DEBUG_LOG 三个常量。它控制错误显示、日志记录，并针对特定请求类型（如 XML-RPC、REST）禁用错误显示。
关键要点
- 使用三个常量：WP_DEBUG（启用调试模式）、WP_DEBUG_DISPLAY（控制错误显示）、WP_DEBUG_LOG（指定日志路径），均在 wp-config.php 中定义。
- WP_DEBUG 为 true 时，报告所有 PHP 通知和 WordPress 内部弃用警告，建议开发环境启用。
- WP_DEBUG_DISPLAY 和 WP_DEBUG_LOG 仅在 WP_DEBUG 为 true 时生效；WP_DEBUG_DISPLAY 可设为 null 以保持全局配置。
- 错误不会在 XML-RPC、REST、ms-files.php 和 Ajax 请求中显示。
- 提供 'enable_wp_debug_mode_checks' 过滤器，允许在非 Web 运行时禁用调试检查。
代码示例
function wp_debug_mode() {
if ( ! apply_filters( 'enable_wp_debug_mode_checks', true ) ) {
return;
}
if ( WP_DEBUG ) {
error_reporting( E_ALL );
if ( WP_DEBUG_DISPLAY ) {
ini_set( 'display_errors', 1 );
} elseif ( null !== WP_DEBUG_DISPLAY ) {
ini_set( 'display_errors', 0 );
}
if ( in_array( strtolower( (string) WP_DEBUG_LOG ), array( 'true', '1' ), true ) ) {
$log_path = WP_CONTENT_DIR . '/debug.log';
} elseif ( is_string( WP_DEBUG_LOG ) ) {
$log_path = WP_DEBUG_LOG;
} else {
$log_path = false;
}
if ( $log_path ) {
ini_set( 'log_errors', 1 );
ini_set( 'error_log', $log_path );
}
} else {
error_reporting( E_CORE_ERROR | E_CORE_WARNING | E_COMPILE_ERROR | E_ERROR | E_WARNING | E_PARSE | E_USER_ERROR | E_USER_WARNING | E_RECOVERABLE_ERROR );
}
if ( defined( 'XMLRPC_REQUEST' ) || defined( 'REST_REQUEST' ) || defined( 'MS_FILES_REQUEST' )
|| ( defined( 'WP_INSTALLING' ) && WP_INSTALLING )
|| wp_doing_ajax() || wp_is_json_request()
) {
ini_set( 'display_errors', 0 );
}
}注意事项
- 在 wp-config.php 中定义常量时，确保正确设置值（如 true/false 或文件路径）。
- 使用 'enable_wp_debug_mode_checks' 过滤器时，需在 WordPress 加载前定义 $wp_filter 全局变量。
- WP_DEBUG_LOG 从 5.1.0 版本起支持文件路径，之前仅支持布尔值。
Sets PHP error reporting based on WordPress debug settings.
Description
Uses three constants: WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG.
All three can be defined in wp-config.php. By default, WP_DEBUG and WP_DEBUG_LOG are set to false, and WP_DEBUG_DISPLAY is set to true.
When WP_DEBUG is true, all PHP notices are reported. WordPress will also display internal notices: when a deprecated WordPress function, function argument, or file is used. Deprecated code may be removed from a later version.
It is strongly recommended that plugin and theme developers use WP_DEBUG in their development environments.
WP_DEBUG_DISPLAY and WP_DEBUG_LOG perform no function unless WP_DEBUG is true.
When WP_DEBUG_DISPLAY is true, WordPress will force errors to be displayed.WP_DEBUG_DISPLAY defaults to true. Defining it as null prevents WordPress from changing the global configuration setting. Defining WP_DEBUG_DISPLAY as false will force errors to be hidden.
When WP_DEBUG_LOG is true, errors will be logged to wp-content/debug.log.
When WP_DEBUG_LOG is a valid path, errors will be logged to the specified file.
Errors are never displayed for XML-RPC, REST, ms-files.php, and Ajax requests.
Source
function wp_debug_mode() {
/**
* Filters whether to allow the debug mode check to occur.
*
* This filter runs before it can be used by plugins. It is designed for
* non-web runtimes. Returning false causes the `WP_DEBUG` and related
* constants to not be checked and the default PHP values for errors
* will be used unless you take care to update them yourself.
*
* To use this filter you must define a `$wp_filter` global before
* WordPress loads, usually in `wp-config.php`.
*
* Example:
*
* $GLOBALS['wp_filter'] = array(
* 'enable_wp_debug_mode_checks' => array(
* 10 => array(
* array(
* 'accepted_args' => 0,
* 'function' => function() {
* return false;
* },
* ),
* ),
* ),
* );
*
* @since 4.6.0
*
* @param bool $enable_debug_mode Whether to enable debug mode checks to occur. Default true.
*/
if ( ! apply_filters( 'enable_wp_debug_mode_checks', true ) ) {
return;
}
if ( WP_DEBUG ) {
error_reporting( E_ALL );
if ( WP_DEBUG_DISPLAY ) {
ini_set( 'display_errors', 1 );
} elseif ( null !== WP_DEBUG_DISPLAY ) {
ini_set( 'display_errors', 0 );
}
if ( in_array( strtolower( (string) WP_DEBUG_LOG ), array( 'true', '1' ), true ) ) {
$log_path = WP_CONTENT_DIR . '/debug.log';
} elseif ( is_string( WP_DEBUG_LOG ) ) {
$log_path = WP_DEBUG_LOG;
} else {
$log_path = false;
}
if ( $log_path ) {
ini_set( 'log_errors', 1 );
ini_set( 'error_log', $log_path );
}
} else {
error_reporting( E_CORE_ERROR | E_CORE_WARNING | E_COMPILE_ERROR | E_ERROR | E_WARNING | E_PARSE | E_USER_ERROR | E_USER_WARNING | E_RECOVERABLE_ERROR );
}
/*
* The 'REST_REQUEST' check here is optimistic as the constant is most
* likely not set at this point even if it is in fact a REST request.
*/
if ( defined( 'XMLRPC_REQUEST' ) || defined( 'REST_REQUEST' ) || defined( 'MS_FILES_REQUEST' )
|| ( defined( 'WP_INSTALLING' ) && WP_INSTALLING )
|| wp_doing_ajax() || wp_is_json_request()
) {
ini_set( 'display_errors', 0 );
}
}
Hooks
- apply_filters( ‘enable_wp_debug_mode_checks’, bool $enable_debug_mode )
-
Filters whether to allow the debug mode check to occur.
Skip to note 2 content
Codex
Usage