深夜调试室，用 WP_DEBUG_LOG 终结 WordPress 白屏、错位与崩溃

凌晨两点,你刚把精心打磨的 functions.php 上传到服务器，刷新页面——白屏，没有任何提示，没有错误代码，只有一片死寂的白色，你打开浏览器控制台，网络请求全是 200 OK，数据库也没挂，这是 WordPress 开发者最熟悉的噩梦，而破解这一切的钥匙，就藏在 wp-config.php 里那个被大多数人忽略的常量：WP_DEBUG_LOG。

很多人知道开启 WP_DEBUG 能把错误显示在页面上，但这在线上环境是灾难——你的访客会看到一堆 PHP 警告，甚至暴露服务器路径，所以我们需要更优雅的调试方式：把错误写入日志文件，而不是打印在屏幕前，打开 wp-config.php，找到 /* 好了！请不要再继续编辑。 */ 这一行之前，加入以下代码：

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

这样,所有 PHP 错误、警告和通知都会写入 /wp-content/debug.log，而页面保持干净，我以六个真实场景，带你把这个日志用到极致。

主题安装后样式错乱，但页面不报错

深夜调试室，用 WP_DEBUG_LOG 终结 WordPress 白屏、错位与崩溃

你新装了一个主题,首页排版全乱，元素重叠，debug.log 里可能只有几条“PHP Notice: Undefined index”，别忽略它们——很多主题的动态 CSS 依赖数组键值，一个未定义的索引会导致 wp_add_inline_style 输出空字符串，排查方法：打开 debug.log，搜索 style.css 或 wp_enqueue_scripts 相关行，如果看到类似：

PHP Notice: Undefined index: bg_color in /themes/mytheme/inc/dynamic-css.php on line 42

修复就是加一个空合并：

$bg_color = $settings['bg_color'] ?? '#ffffff';

然后清空 debug.log，刷新页面，确认无新日志。

插件激活后网站崩溃，后台也进不去

这是最棘手的,你通过 FTP 把插件文件夹改名，网站恢复，但你想知道为什么，开启 WP_DEBUG_LOG 后，再次激活插件，然后立刻刷新前端——崩溃瞬间，日志会记录致命错误。

PHP Fatal error: Uncaught Error: Call to undefined function wp_get_current_user() in /plugins/bad-plugin/init.php:15

这是因为插件在 plugins_loaded 钩子之前就调用了用户函数，修复：要么等 init 钩子，要么在插件主文件加：

if ( ! function_exists( 'wp_get_current_user' ) ) {
    require_once ABSPATH . 'wp-includes/pluggable.php';
}

但更安全的恢复方式是：通过 FTP 进入 /wp-content/plugins/，把问题插件重命名为 bad-plugin.disabled，然后登录后台重新评估。

古腾堡编辑器兼容问题——区块白屏或保存失败

你开发的自定义区块在编辑器里显示“此区块遇到错误”，开启 debug.log 后，打开编辑器，日志会出现：

PHP Fatal error: Uncaught Error: Call to undefined function register_block_type_from_metadata() in /themes/mytheme/blocks/register.php:5

这说明你的主题在 init 钩子外调用了区块注册函数，正确做法：

add_action( 'init', function() {
    register_block_type_from_metadata( __DIR__ . '/blocks/hello' );
} );

检查 block.json 中的 apiVersion 是否与你的 WP 版本匹配，不匹配也会导致 JS 控制台报错，但 debug.log 不会记录 JS 错误——这是 PHP 日志的边界，需要配合浏览器控制台。

页面构建器插件冲突——短代码失效或布局崩溃

你同时用了 Elementor 和另一个短代码插件，在 debug.log 中看到：

PHP Warning: call_user_func_array() expects parameter 1 to be a valid callback, function 'my_shortcode_handler' not found

这通常是插件加载顺序问题,修复：在主题的 functions.php 中强制调整优先级：

add_action( 'plugins_loaded', function() {
    remove_shortcode( 'my_shortcode' );
    add_shortcode( 'my_shortcode', 'my_shortcode_handler' );
}, 20 );

在 wp-config.php 中临时关闭构建器的“安全模式”，再逐一切换短代码标签测试。

子主题创建与修改——错误定位的关键

很多问题源于直接修改父主题,正确做法：创建 /themes/parent-theme-child/style.css

/*
Theme Name: Parent Child
Template: parent-theme
*/

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
} );

get_template_part( 'template-parts/content', get_post_format(), [ 'class' => 'featured' ] );

PHP Warning: get_template_part() expects parameter 3 to be array, null given

if ( version_compare( get_bloginfo('version'), '5.5', '>=' ) ) {
    get_template_part( 'template-parts/content', get_post_format(), [ 'class' => 'featured' ] );
} else {
    get_template_part( 'template-parts/content', get_post_format() );
}