この記事では、WordPress のデバッグモードを有効化し、WordPress debug.log ファイルを作成する方法を説明します。
WordPress 本番サイトで致命的エラーや真っ白なページに遭遇していませんか?
WP STAGING を試して、本番サイトでそのような致命的エラーを防ぎましょう!
Staging サイトで作業することがなぜ重要なのか、こちらの開発者の短編小説をお読みください。
WordPress サイトを開いて空白ページや 500 エラーが表示されるとき、WordPress は原因を即座に特定できるエラーメッセージを抑制しています。WordPress デバッグログを有効化すると、WordPress はすべての PHP エラー・警告・通知を wp-content/debug.log ファイルに書き込むようになり、どの Plugin・Theme・コード行が原因なのかを正確に確認できます。
要約: 次の 3 つの定数を
wp-config.phpの/* That's all, stop editing! Happy publishing. */行の直前に追加してください —define( 'WP_DEBUG', true );、define( 'WP_DEBUG_LOG', true );、define( 'WP_DEBUG_DISPLAY', false );。保存後にページを再読み込みすると、WordPress はすべての PHP エラーをwp-content/debug.logに書き込みます。トラブルシューティングが完了したら、本番に PUSH する前に WordPress デバッグモードを無効化してください。
Contents
Hosting 環境別の WordPress デバッグモード
wp-config.php へのアクセス方法と debug.log の保存先は、Hosting 環境によって異なります。お使いの構成に合うセクションをご利用ください。
共有 Hosting (cPanel / FTP)
Bluehost、SiteGround、Hostinger などの共有ホストでは、wp-config.php は WordPress のルートディレクトリ (通常は public_html/) にあります。cPanel のファイルマネージャーや FileZilla などの FTP クライアントを使って編集してください。
よくある権限問題: WordPress が debug.log を書き込めない場合、wp-content/ ディレクトリが Web サーバーから書き込み可能である必要があります。ディレクトリの標準権限は 755 です。共有ホストで 777 に設定してはいけません。これはディレクトリを全員から書き込み可能にしてしまい、セキュリティリスクとなります。
WP STAGING のサポートチケットでは、共有 Hosting が debug.log が無言で失敗する場面として最も多いです。多くの共有ホストは、WordPress に debug.log を作成させる代わりに、PHP エラーを自身のサーバー側ログに捕捉するためです。WP_DEBUG を有効化してもファイルが現れない場合は、Hosting プロバイダーに PHP エラーログの保存場所を尋ねてください。
VPS / マネージドサーバー (SSH)
SSH アクセスがあれば、コマンドラインから直接 wp-config.php を編集できます:
nano /var/www/html/wp-config.php保存後、ログをリアルタイムでテイルして、エラーが発生する様子を確認できます:
tail -f /var/www/html/wp-content/debug.logdebug.log が作成されない場合は、wp-content/ ディレクトリが Web サーバーユーザー (Ubuntu/Debian では www-data、CentOS/AlmaLinux では apache または nginx) の所有であることを確認してください:
ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/ローカル開発環境 (LocalWP / DevKinsta / XAMPP)
debug.log は同じ wp-content/debug.log の場所に現れますが、ベースパスはローカル環境によって異なります:
- LocalWP:
~/Local Sites/<site-name>/app/public/wp-content/debug.log - DevKinsta:
~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log - XAMPP on Windows:
C:xampphtdocs<site-name>wp-contentdebug.log
ローカル環境では、Web サーバーとユーザーアカウントが同じプロセスとして実行されるため、権限の問題はほとんど発生しません。debug.log がまったく現れない場合は、wp-config.php が WordPress のルートにあり、親ディレクトリにないことを確認してください。
WP STAGING の Staging サイト
WP STAGING を使った当社のテストでは、Staging クローン上でデバッグモードを有効化するのが最も安全な方法です。クローンは本番サイトの正確なコピーであるため、再現したエラーは本番環境と一致し、実際の訪問者に影響を与えません。
Staging サイトでデバッグモードを有効化するには、Staging ディレクトリ内の wp-config.php を編集してください。WP STAGING は Staging サイトを独自の wp-config.php を持つ別のサブディレクトリまたはサブドメインとして作成するため、そこでの変更は本番サイトの WP_DEBUG 設定に影響しません。
Staging サイトにログインできない場合、デバッグログは最初に確認すべき場所です。Staging でのログイン失敗は、ほとんどの場合ログにのみ表示される PHP の致命的エラーです。
WordPress デバッグモードの有効化方法
WordPress インストールの wp-config.php ファイルでいくつかの行を編集することで、WordPress の「デバッグモード」を有効化できます:
- cPanel にログインするか、FTP 経由でサイトにログインします。
- cPanel のファイルマネージャーまたは FTP クライアントを使って
wp-config.phpファイルを編集します。 - 下記の行を
wp-config.phpにコピーするか、すでに存在する場合は値を true に変更します:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );注意: 行は表示どおり正確にコピーし、セミコロンや他の文字を忘れないようにしてください!
- コピーした行を、次の行の直前に貼り付けます
/* That's all, stop editing! Happy publishing. */
サイトを再読み込みすると、WordPress はすべての PHP エラーを debug.log ファイルに書き込みます。
WordPress はそのファイルを wp-content/debug.log フォルダに保存します。
WordPress フロントエンドにエラーを表示する
あなたや訪問者がフロントページで PHP の警告とエラーメッセージを目にすることになります。
セキュリティ上の理由から、サイトのエラーを修正した後は WP_DEBUG_DISPLAY 定数を無効化してください。
debug.log ファイルを有効化する代わりに、デバッグログのエラーを画面上に直接表示したい場合は、define( 'WP_DEBUG_DISPLAY', false ); の行を変更してください。
次のようにリネームします: define( 'WP_DEBUG_DISPLAY', true );。
WordPress が debug.log ログファイルを作成しない
一部の Hosting プロバイダー[1] は、WordPress debug.log の作成を許可していません。これらのプロバイダーはすべての PHP エラーをキャッチし、WordPress に別のログファイルへ書き込ませます。
WordPress が debug.log を作成できない場合、次のデシジョンツリーに従って原因を見つけてください:
1. 代替のログファイルを探します。 サイトルートに error_log という名前のファイルがないか、または /logs/ フォルダがないか確認してください。HostGator を含む多くの共有ホストは、WordPress が debug.log を書き込むのを許可せず、PHP エラーを独自のサーバー側ログにリダイレクトします。ログファイルが見つからない場合は、Hosting プロバイダーに PHP エラーログの保存場所を尋ねてください。
2. ディレクトリ権限を確認します。 wp-content/ は Web サーバーから書き込み可能である必要があります。SSH アクセスのあるサーバーでは、次を実行してください:
ls -la /path/to/wp-content/このディレクトリは www-data (Ubuntu/Debian) または apache (CentOS) の所有である必要があります。標準権限は 755 です。ディレクトリが root の所有で Web サーバーユーザーが書き込めない場合、debug.log は無言で作成に失敗します。
3. display_errors が設定を上書きしていないか確認します。 一部のサーバー php.ini 設定や .htaccess ディレクティブが php_flag display_errors Off を設定している場合、WP_DEBUG_DISPLAY が true でも出力が抑制されることがあります。Hosting コントロールパネルの PHP 設定を確認するか、ホストに問い合わせてください。
4. must-use Plugin がエラーを抑制していないか確認します。 wp-content/mu-plugins/ 内のファイルはすべてのものより先に読み込まれ、WordPress のエラーハンドラーを上書きできます。ホストがエラーを横取りする must-use Plugin をインストールしている場合、debug.log の書き込みを妨げる可能性があります。wp-content/mu-plugins/ ディレクトリが存在する場合は、その中のファイルを確認してください。
5. error_reporting のレベルを確認します。 error_reporting が制限的すぎる設定 (たとえば E_ERROR のみ) になっている場合、PHP は警告や通知をログに記録しません。WordPress は WP_DEBUG が true のときに error_reporting(E_ALL) を設定しますが、Plugin やサーバー設定が WordPress 読み込み後にこれを変更することがあります。すべての定数と各レベルがカバーする範囲については、PHP error_reporting ドキュメントをご覧ください。
6. ログパスのディレクトリが存在することを確認します。 すでに WP_DEBUG_LOG をカスタムパスに設定している場合、そのパスのディレクトリが存在し、Web サーバーから書き込み可能であることを確認してください。
あるいは、上記の方法を使って
define( 'WP_DEBUG_DISPLAY', false ); を
define( 'WP_DEBUG_DISPLAY', true ); に変更できます。
これがうまく動作すれば、関連するエラーがフロントエンドに表示され、致命的エラーの解決に役立ちます。
WordPress デバッグモードの有効化に関する詳細な手順は、WordPress デバッグドキュメントでご覧いただけます。
本記事執筆時点で: [1] HostGator
debug.log が生成されないときに致命的エラーをデバッグする代替方法
致命的エラーをトラブルシュートするために WP_DEBUG モードを有効化したとき、Hosting プロバイダーが debug.log ファイルの作成を妨げていることが分かる場合があります。WP_DEBUG_DISPLAY を true に設定しても、フロントエンドにエラーが必ずしも表示されるとは限りません。
この状況で行き詰まっている場合、他に何も効かないときに機能する回避策をご紹介します。
wp-config.php でエラー表示を強制する
このスニペットは致命的エラーの表示を強制します:
register_shutdown_function(function () {
$error = error_get_last();
if ($error) {
print_r($error);
}
});
🚨 デバッグ後はスニペットを削除することを忘れずに、安全にロールバックできる FTP アクセスがあるときのみ使用してください。
WordPress デバッグログを読む
debug.log が存在するようになったら、任意のテキストエディタで開きます。各行は次のパターンに従います:
[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N各エラークラスの意味と対応すべき時期は次のとおりです:
PHP Fatal error — PHP は実行を停止しました。これは常に空白ページや 500 エラーの原因です。ログエントリのファイルパスと行番号から、正確にどこを確認すべきかが分かります。エントリで指名されたファイルの Plugin または Theme を見つけて無効化し、原因を確認してください。
PHP Warning — PHP は予期しない何かに遭遇しましたが、実行は継続しました。警告自体は空白ページを引き起こしませんが、別の条件下で致命的エラーに変わるバグを示している場合がよくあります。PHP の設定制限に関する PHP 警告を特定するために WordPress デバッグログを有効化している場合、フォームが多い Plugin からの max_input_vars 警告がよくあるエントリです。
PHP Notice — PHP は未定義変数などの潜在的な問題を記録しました。通知は本番環境で実際のバグを示すことはまれですが、同じ通知が 1 ページの読み込みで何千回も表示される場合、パフォーマンスを劣化させるループや再帰の問題を示すことがあります。
$wpdb データベースエラー — WordPress database error で始まる行は、クエリが失敗したことを示します。これらは通常、形式が崩れた SQL クエリを生成する Plugin、またはクエリの対象となる WordPress データベーステーブルの問題を指しています。エラーメッセージには失敗したクエリが含まれており、原因の Plugin を簡単に特定できます。
致命的エラーや繰り返される警告を見つけたら、ログエントリのファイルパスを確認してください。Plugin や Theme に属している場合は、無効化してページを再読み込みし、ログエントリが止まることを確認してください。
デバッグログで WordPress の REST API エラーが表面化した場合、ログエントリは通常、失敗した関数の正確な名前を示しています — そこから専用ガイドに従ってください。ERR_CONNECTION_REFUSED エラーが表面化した場合、これらは PHP ではなくサーバーやネットワーク層が原因です。414 Request-URI Too Large エラーの場合、ログは通常、大きすぎる URL を生成している Plugin を特定します。
debug.log の場所を変更する
定数 WP_DEBUG_LOG の値を変更することで、WordPress がエラーログに使用するパスを変更できます。
wp-config.php を開き、WP_DEBUG_LOG を含む行を見つけてください。
検索: define( 'WP_DEBUG_LOG', true );
次のように変更: define( 'WP_DEBUG_LOG', '/logs/errors.log' );
これにより、WordPress がエラーメッセージを別のファイルパスに書き込めるようになります。
保存先パスには /dev/stderr や /dev/stdout も使えます。これは、すべてのログを共有の出力ストリームに集めたい Docker などのコンテナ化環境で便利です。
トラブルシューティング後に WordPress でデバッグモードを無効化する
調査が完了したら、すぐにデバッグモードを無効化してください。debug.log ファイルはデフォルトで Web から wp-content/debug.log でアクセスでき、データベースエラーの詳細、ファイルパス、その他公開して読まれるべきではないサーバー情報が含まれている可能性があります。
debug.log ファイルを削除し、define( 'WP_DEBUG', true ); を define( 'WP_DEBUG', false ); に戻して、それ以上のエラーログを無効化してください。
Staging サイトで作業しているときは、常に本番に PUSH する前に WordPress デバッグモードを無効化してください。WP STAGING の PUSH ワークフローは、クローンが本番サイトを上書きする前に WP_DEBUG が無効になっていることを確認する適切なチェックポイントです。
