はじめに
WordPressで問題が発生したとき、「白い画面」「500エラー」「動作がおかしい」など様々な症状が起きます。体系的なデバッグ手順を身につけることで、問題の原因を素早く特定・解決できます。
症状・原因
デバッグが必要になる主なケース：
- 真っ白な画面（WSOD）が表示される
- エラーメッセージが表示されない
- 特定の条件でのみ問題が再現する
- プラグイン間の競合が疑われる
解決手順
ステップ1：wp-config.phpでデバッグモードを有効化する
// wp-config.php
// 開発環境: 全エラーを表示
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true); // wp-content/debug.log に記録
define('WP_DEBUG_DISPLAY', false); // 画面には表示しない（本番では必ずfalse）
define('SCRIPT_DEBUG', true); // 圧縮していないJS/CSSを使用
define('SAVEQUERIES', true); // 全SQLクエリを保存
// エラーレポートレベル（ローカル開発時）
// define('WP_DEBUG_DISPLAY', true); // 画面に表示（ローカルのみ）# デバッグログをリアルタイムで監視
tail -f wp-content/debug.log
# エラーの種類ごとに絞り込む
grep "PHP Fatal" wp-content/debug.log | tail -20
grep "PHP Warning" wp-content/debug.log | tail -20
# ログが大きすぎる場合はローテーション
> wp-content/debug.log # ログをクリアステップ2：効果的なデバッグ出力を行う
// var_dump の代わりに使うユーティリティ関数
function wp_debug_log(mixed $data, string $label = ''): void {
if (!WP_DEBUG_LOG) return;
$output = $label ? "[{$label}] " : '';
if (is_array($data) || is_object($data)) {
$output .= print_r($data, true);
} elseif (is_bool($data)) {
$output .= $data ? 'true' : 'false';
} elseif (is_null($data)) {
$output .= 'NULL';
} else {
$output .= $data;
}
// バックトレースを含める
$trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
$caller = $trace[0]['file'] . ':' . $trace[0]['line'];
$short_path = str_replace(ABSPATH, '', $caller);
error_log("[WP_DEBUG] {$short_path} → {$output}");
}
// 使用例
wp_debug_log($post, 'Post Object');
wp_debug_log(get_option('active_plugins'), 'Active Plugins');
wp_debug_log(defined('WP_DEBUG') && WP_DEBUG, 'Debug Mode');
// フックの実行順序を調べる
add_action('all', function($hook) {
if (str_contains($hook, 'my_plugin')) {
wp_debug_log($hook, 'Hook fired');
}
});ステップ3：問題を段階的に切り分ける
# テーマを問題のないもの（Twenty Twenty-Four）に切り替え
wp theme activate twentytwentyfour
# 全プラグインを無効化
wp plugin deactivate --all
# プラグインを1つずつ有効化して問題を再現
wp plugin activate akismet
wp plugin activate woocommerce
# 問題が再現したプラグインが犯人
# データベースの問題を確認
wp db check
wp db repair
# WordPress本体のファイルが改ざんされていないか確認
wp core verify-checksums
# プラグインのファイルを確認
wp plugin verify-checksums akismet woocommerceステップ4：特定のエラーを診断する
// 白い画面(WSOD)の場合 - OOMエラーを検出
add_action('shutdown', function() {
$error = error_get_last();
if ($error && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR])) {
wp_debug_log($error, 'Fatal Error');
}
});
// 特定のフックで止まっている場合
add_action('wp_head', function() {
wp_debug_log('wp_head start', 'Hook');
}, 0);
add_action('wp_head', function() {
wp_debug_log('wp_head end', 'Hook');
}, PHP_INT_MAX);
// Ajax リクエストのデバッグ
add_action('wp_ajax_my_action', function() {
wp_debug_log($_POST, 'Ajax POST');
// ... 処理 ...
}, 1);
// 特定のクエリを監視
add_filter('query', function($sql) {
if (str_contains($sql, 'wp_custom_table')) {
wp_debug_log($sql, 'Custom Table Query');
}
return $sql;
});ステップ5：WP-CLIで高度な診断を行う
# サイト全体の健全性チェック
wp doctor check --all
# 特定のチェックのみ実行
wp doctor check core-update
wp doctor check plugin-active-count # 有効プラグイン数が多すぎないか
wp doctor check constant-savequeries # SAVEQUERIES が本番でONになっていないか
# データベースの問題診断
wp db query "SELECT * FROM wp_options WHERE option_name LIKE '_transient_%' LIMIT 5"
wp db query "SELECT count(*) FROM wp_postmeta"
# 孤立したメタデータを確認
wp db query "
SELECT count(*) FROM wp_postmeta pm
LEFT JOIN wp_posts p ON pm.post_id = p.ID
WHERE p.ID IS NULL"
# PHP設定を確認
wp eval "phpinfo(INFO_GENERAL | INFO_CONFIGURATION);" | grep -E "memory_limit|max_execution|upload_max"
# xdebugのプロファイリング（ローカル開発）
# XDEBUG_SESSION=1 wp eval 'get_posts();'注意事項
WP_DEBUG_DISPLAY = trueは必ずローカル/ステージング環境のみで使用してくださいSAVEQUERIESは本番環境ではオフにしてください（メモリ使用量増加）- デバッグログが大きくなりすぎないよう定期的にクリアしてください
- xdebugは本番環境には絶対に入れないでください
まとめ
WordPressのデバッグは、①WP_DEBUGの適切な設定、②error_logと独自デバッグ関数の活用、③プラグイン/テーマの段階的な切り分け、④フック・クエリ・Ajax等の特定箇所の監視、⑤wp doctorコマンドによる総合診断の流れで体系的に行います。