WordPress開発者向けチートシート：デバッグモード関連定数マスター
WordPressサイトの開発や運用中に問題が発生した際、その原因を効率的に特定し解決するために不可欠なのが「デバッグモード」です。WordPressには、このデバッグモードの挙動を細かく制御するためのいくつかの定数が用意されており、これらをwp-config.phpファイルに設定することで、エラー情報の表示やログ記録、スクリプトの読み込み方などを変更できます。
これらのデバッグ関連定数を正しく理解し活用することは、開発効率の向上、迅速なトラブルシューティング、そして最終的にはより安定したサイト運用に繋がります。この記事では、主要なデバッグ関連定数をチートシート形式で詳しく解説します。
デバッグ関連定数の設定場所
ここで紹介するデバッグ関連定数は、すべてWordPressのルートディレクトリにあるwp-config.phpファイルに記述します。記述する場所は、以下のコメント行よりも前にしてください。
|
1 2 3 4 |
/* That's all, stop editing! Happy publishing. */ /** Absolute path to the WordPress directory. */ // (これ以降の行) |
wp-config.phpは非常に重要な設定ファイルですので、編集する際は必ずバックアップを取り、慎重に作業を行ってください。
主要デバッグ関連定数一覧
WordPressのデバッグ機能を制御するためにwp-config.phpで使用できる主要な定数を分類しました。各定数の説明の冒頭には、そのデバッグ時の重要度や利用頻度を星の5段階評価で示しています。星の数の目安は以下の通りです。
★★★★★：ほぼ全ての開発で頻繁に利用され、基本かつ非常に重要なパラメータ
★★★★☆：高頻度で利用され、多くの一般的なカスタマイズで役立つ重要なパラメータ
★★★☆☆：中程度の頻度で利用され、特定の機能を実現する際に便利なパラメータ
★★☆☆☆：利用頻度はやや低めですが、特定の要件や細かな制御を行いたい場合に役立つパラメータ
★☆☆☆☆：利用頻度は低く、非常に限定的な状況や高度なカスタマイズでのみ使用されるパラメータ
| 定数名 | 主な役割・説明 (重要度/利用頻度) | 設定値の例 | デフォルトの挙動（未定義時） | 詳細・注意点 |
|---|---|---|---|---|
WP_DEBUG |
★★★★★ WordPressのメインデバッグモードを有効または無効にします。 trueにすると、PHPのエラー、警告、注意 (Notice) が表示されるようになります。 |
truefalse |
false (デバッグモード無効) |
開発中はtrueに設定することを強く推奨します。本番環境では通常falseにしますが、エラーログ取得のために一時的にtrueにすることもあります（後述）。 |
WP_DEBUG_LOG |
★★★★★WP_DEBUGがtrueの場合に、全てのエラーと警告をwp-content/debug.logファイルに記録します。画面表示を抑制しつつログだけ取得したい場合に便利です。 |
truefalse |
false (ログ記録無効) |
WP_DEBUGがfalseの場合は効果がありません。ログファイルへの書き込み権限が必要です。 |
WP_DEBUG_DISPLAY |
★★★★★WP_DEBUGがtrueの場合に、エラーや警告をHTMLページ内に直接表示するかどうかを制御します。 |
truefalsenull (PHP設定に依存) |
true (エラーを画面表示) |
開発中はtrueが便利ですが、本番環境でエラーを一般ユーザーに見せたくない場合はfalseに設定し、WP_DEBUG_LOGをtrueにしてログファイルで確認します。 |
SCRIPT_DEBUG |
★★★★☆ WordPressがコア、プラグイン、テーマで読み込むCSSやJavaScriptファイルについて、通常の圧縮版 (minified) ではなく、開発用の非圧縮版（デバッグしやすい版）を読み込むようにします。 |
truefalse |
false (圧縮版を使用) |
JavaScriptのエラーを追跡したり、CSSの構造を理解したりするのに非常に役立ちます。フロントエンド開発時にはtrueが推奨されます。 |
SAVEQUERIES |
★★★★☆ 実行された全てのデータベースクエリをグローバル配列 ( $wpdb->queries) に保存します。これにより、各クエリの実行時間や呼び出し元を分析できます。 |
truefalse |
false (クエリ記録無効) |
サイトのパフォーマンスボトルネック（特に遅いクエリ）を特定するのに役立ちます。Query Monitorプラグインなどと併用すると非常に強力ですが、サイトのパフォーマンスに若干影響を与えるため、常時有効にするのは避け、デバッグ時のみ使用します。 |
WP_ENVIRONMENT_TYPE |
★★★★☆ (WP 5.5以降) 現在のWordPress環境が「開発(development)」「ステージング(staging)」「本番(production)」のいずれであるかを定義します。 |
'development''staging''production''local' (WP 5.5.1以降) |
'production' (何も設定しない場合) |
この設定に応じて、一部のWordPressの挙動（例: WP_DEBUGのデフォルト値の提案、一部テーマやプラグインの動作）が変わることがあります。開発環境では'development'や'local'を設定することが推奨されます。 |
サンプルコード集 (wp-config.phpへの記述例)
以下に、一般的なシナリオに合わせたwp-config.phpへの記述例を示します。
1. 開発環境向けの推奨設定
開発中は、エラーを積極的に表示・記録し、デバッグしやすいようにします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
// WordPress デバッグモードを有効化 define( 'WP_DEBUG', true ); // エラーや警告を画面に表示する (開発中は便利) define( 'WP_DEBUG_DISPLAY', true ); // @ini_set( 'display_errors', 1 ); // PHPレベルでのエラー表示も有効にする場合 (WP_DEBUG_DISPLAYがnullまたはfalseの時に役立つ) // エラーや警告を debug.log ファイルに記録する define( 'WP_DEBUG_LOG', true ); // 開発用の非圧縮版 JS/CSS を読み込む define( 'SCRIPT_DEBUG', true ); // データベースクエリを記録する (Query Monitorプラグイン等で確認) define( 'SAVEQUERIES', true ); // 環境タイプを「開発」に設定 define( 'WP_ENVIRONMENT_TYPE', 'development' ); /* That's all, stop editing! Happy publishing. */ |
2. 本番環境向けのエラーログ取得設定（推奨）
本番環境では、エラーを一般ユーザーに見せるべきではありませんが、問題発生時のためにエラーログは記録しておきたいものです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
// WordPress デバッグモード自体は有効にする (ログ出力のため) define( 'WP_DEBUG', true ); // しかし、エラーや警告を画面には表示しない define( 'WP_DEBUG_DISPLAY', false ); @ini_set( 'display_errors', 0 ); // PHPレベルでもエラー表示を抑制 // エラーや警告を debug.log ファイルに記録する define( 'WP_DEBUG_LOG', true ); // 本番環境では圧縮版スクリプトを使用 define( 'SCRIPT_DEBUG', false ); // 通常、本番環境ではクエリ記録は無効 define( 'SAVEQUERIES', false ); // 環境タイプを「本番」に設定 define( 'WP_ENVIRONMENT_TYPE', 'production' ); /* That's all, stop editing! Happy publishing. */ |
注意: WP_DEBUGがfalseの場合、WP_DEBUG_LOGとWP_DEBUG_DISPLAYの設定はWordPressコアのデフォルトでは無視されます。本番環境でエラーログを取得しつつ画面表示を抑制するには、上記のようにWP_DEBUGをtrueにし、WP_DEBUG_DISPLAYをfalseに設定するのが一般的です。
デバッグ情報の確認方法
- 画面上のエラー表示:
WP_DEBUGがtrueで、かつWP_DEBUG_DISPLAYがtrue（または未設定）の場合、PHPのエラー、警告、注意がブラウザ画面に直接表示されます。 debug.logファイル:WP_DEBUGがtrueで、かつWP_DEBUG_LOGがtrueの場合、エラーログはwp-contentディレクトリ内のdebug.logファイルに書き出されます。このファイルを確認することで、画面には表示されないエラーや、過去に発生したエラーの履歴を追跡できます。- データベースクエリ:
SAVEQUERIESをtrueに設定すると、実行されたSQLクエリが$wpdb->queriesというグローバル配列に保存されます。「Query Monitor」のような開発者向けプラグインを使用すると、これらのクエリ情報（実行時間、呼び出し元など）を非常に分かりやすく確認できます。 - 非圧縮スクリプト:
SCRIPT_DEBUGをtrueにすると、ブラウザの開発者ツールの「ソース」タブや「ネットワーク」タブで、*.min.jsや*.min.cssの代わりに、可読性の高い非圧縮版のファイルが読み込まれていることを確認できます。これにより、JavaScriptのエラー箇所の特定などが容易になります。
よくある質問 (FAQ)
- Q1: 本番環境で
WP_DEBUGをtrueに設定したままにしても大丈夫ですか？ - A1:
いいえ、一般的に本番環境で
WP_DEBUGをtrueにし、かつWP_DEBUG_DISPLAYもtrue（または未設定）のままにするのは非推奨です。エラーメッセージが一般ユーザーに表示されてしまうと、サイトの脆弱性に関する情報（ファイルパスなど）を攻撃者に与えてしまう可能性があります。本番環境でエラーを調査したい場合は、
WP_DEBUG_DISPLAYをfalseにし、WP_DEBUG_LOGをtrueにしてログファイルで確認するようにしましょう。調査が完了したら、WP_DEBUGをfalseに戻すのが理想的です（ただし、上記の本番環境向けログ取得設定のように運用する方法もあります）。 - Q2:
debug.logファイルが生成されません。なぜですか？ - A2: いくつか原因が考えられます。
WP_DEBUGがtrueに設定されていない（または途中でfalseに上書きされている）。WP_DEBUG_LOGはWP_DEBUGがtrueの場合にのみ機能します。wp-contentディレクトリにウェブサーバーからの書き込み権限がない。wp-config.phpの記述場所が間違っている（/* That's all, stop editing! */より後に記述しているなど）。- そもそもエラーが発生していない（PHPの
error_reportingレベルが低い設定になっているなど）。
- Q3:
WP_ENVIRONMENT_TYPEを設定すると、具体的に何が変わるのですか？ - A3:
WP_ENVIRONMENT_TYPEは、WordPress自体や一部のテーマ・プラグインが、現在の環境に応じて動作を調整するためのものです。例えば、'development'に設定すると、WordPressはデフォルトでWP_DEBUGをtrueにすべきだと判断しやすくなったり（ただし直接上書きはしません）、一部のテーマが開発者向けの追加情報を表示したりすることがあります。また、将来的にこの定数を参照する機能が増える可能性があります。一貫した開発・ステージング・本番環境の管理に役立ちます。
まとめ
WordPressのデバッグ関連定数は、開発プロセスをスムーズにし、問題発生時の原因究明を迅速化するための強力なツールです。特に開発環境ではこれらの定数を積極的に活用し、エラーや警告に早期に気づき対処することが、品質の高いサイト構築に繋がります。本番環境では、ユーザーにエラー情報を見せないように配慮しつつ、必要なログは確実に取得できるように設定することが重要です。これらの知識を身につけ、より効率的で安全なWordPress開発・運用を目指しましょう。
私たちは、WordPressサイトのパフォーマンスチューニングやセキュリティ強化、そして複雑なトラブルシューティングなど、技術的な専門知識を要する課題解決を得意としています。埼玉県川越市を拠点に活動しておりますが、リモートでのサポートも可能ですので、全国どちらからでもお気軽にご相談ください。
WordPress顧問エンジニアサービスをご検討くださいね。専門家の視点から、あなたのサイト運用や開発プロジェクトを強力にバックアップします。
