深夜十一点，客户发来消息：“网站白屏了。”你打开页面，只看到一行冰冷的提示：“There has been a critical error on this website.” 这时候，你需要的不是运气，而是 WP_DEBUG。
很多开发者知道要在 wp-config.php 里加一行 define('WP_DEBUG', true);，但真正会用、用好它的人并不多，今天我们就以实战问题为线索，把 WP_DEBUG 的完整用法拆开讲清楚。
先搞清楚WP_DEBUG到底该开哪几个开关
在 wp-config.php 中，WP_DEBUG 实际上是一组常量：
WordPress开启WP_DEBUG完全指南，从样式错乱到插件崩溃的排查实战
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);
WP_DEBUG：总开关。WP_DEBUG_LOG：把错误写入/wp-content/debug.log。WP_DEBUG_DISPLAY：是否在页面上直接显示错误，生产环境务必设为false。SCRIPT_DEBUG：加载未压缩的 JS/CSS,排查前端问题时非常有用。
建议本地开发用 DISPLAY=true，线上排查用 LOG=true + DISPLAY=false,避免把报错暴露给访客。
主题安装后样式错乱怎么排查
新主题装上去，页面结构还在但样式全丢了，先开 WP_DEBUG 看有没有报错,再检查资源加载。
在 functions.php 中确认样式是否用正确的方式注册：
function mytheme_enqueue_assets() {
wp_enqueue_style(
'mytheme-style',
get_stylesheet_uri(),
array(),
wp_get_theme()->get('Version')
);
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');
如果用了 get_template_directory_uri() 但主题是子主题，就会指向父主题目录，子主题里应改用 get_stylesheet_directory_uri()，开启 SCRIPT_DEBUG 后，浏览器里能直接看到是哪个 CSS 404,路径问题一目了然。
插件激活后网站崩溃怎么恢复
插件一激活就白屏,通常有两种恢复方式：
FTP重命名插件目录
把 /wp-content/plugins/问题插件 改名为 问题插件.disabled，WordPress 会自动停用它。
通过 debug.log 定位
开启 WP_DEBUG_LOG 后，错误会写到 wp-content/debug.log,典型报错：
PHP Fatal error: Uncaught Error: Call to undefined function plugin_prefix_init()
in /wp-content/plugins/bad-plugin/bad-plugin.php:42这说明插件调用了未定义的函数，可能是加载顺序问题，你可以在插件主文件中检查是否用了 plugins_loaded 钩子：
add_action('plugins_loaded', 'plugin_prefix_init');
如果函数定义在 init 之后，就会报未定义,调整钩子优先级即可。
古腾堡编辑器兼容问题怎么处理
自定义区块在编辑器里报 “This block contains unexpected or invalid content”，开启 WP_DEBUG 后，浏览器控制台会给出更具体的 React 报错。
检查 block.json 和注册代码：
register_block_type(__DIR__ . '/build', array(
'render_callback' => 'my_render_block',
));
常见坑是 attributes 类型不匹配，比如保存时是字符串，读取时按数字处理，就会触发校验失败，在 edit.js 和 save.js 中保持属性类型一致，并用 wp.blocks.validateBlock 做自测。
页面构建器插件冲突怎么解决
Elementor 或 WPBakery 与主题冲突时，页面会卡在加载动画或短代码原样输出，开启 WP_DEBUG_LOG,看是否出现：
PHP Notice: Undefined index: settings in /elementor/includes/widgets/...这类问题多半是主题覆盖了构建器的模板，检查主题的 single.php 是否误用了 the_content() 之外的输出方式,正确做法是保留构建器接管内容：
if (class_exists('Elementor\Plugin')) {
echo \Elementor\Plugin::$instance->frontend->get_builder_content(get_the_ID());
} else {
the_content();
}
同时把 WP_DEBUG_DISPLAY 设为 false，避免构建器 AJAX 请求被 HTML 报错污染，返回 JSON 解析失败。
子主题创建和修改方法
子主题是排查问题的安全区，创建 /wp-content/themes/mytheme-child/style.css：
/* Theme Name: MyTheme Child Template: mytheme Version: 1.0 */
再建 functions.php：
add_action('wp_enqueue_scripts', function() {
wp_enqueue_style('parent-style', get_template_directory_uri() . '/style.css');
wp_enqueue_style('child-style', get_stylesheet_uri(), array('parent-style'));
});
注意 Template 必须与父主题目录名完全一致，开启 WP_DEBUG 后，如果父主题没找到，会提示 “The parent theme is missing”,直接定位到拼写问题。
常用函数调用报错怎么修复
get_the_ID() 在循环外返回 false，wp_get_post_terms() 传错 taxonomy 会报 WP_Error，开启 WP_DEBUG 后，用 error_log() 打印上下文：
$terms = wp_get_post_terms(get_the_ID(), 'category');
if (is_wp_error($terms)) {
error_log('Terms error: ' . $terms->get_error_message());
}
再用 var_dump() 或 print_r() 配合 WP_DEBUG_DISPLAY 快速查看返回值结构，生产环境记得关掉显示,只保留日志。
最后提醒
排查完问题，把 WP_DEBUG 关掉,或者至少设成：
define('WP_DEBUG', false);
调试是手术刀，不是日常工具，开着它上线，等于把病历贴在门口，学会用它，你才能在深夜的白屏面前,稳稳地找到那一行报错。
发表评论