WP_Queryで投稿が表示されない原因と確認チェックリスト

まず症状を整理する

WP_Queryで「投稿が表示されない」といっても、実際には4つの状態があります。テンプレートが実行されていない、クエリが0件、投稿は取得できているが出力されていない、独自ループ後の別コンテンツが違う投稿を参照している、のどれかです。

たとえば have_posts() が false になっているなら、WP_Queryが条件に合う投稿を見つけられていない状態です。一方で、have_posts() は true なのにタイトルが出ないなら、ループ内の出力やテンプレートタグの使い方を確認する必要があります。

最初に症状を分ける理由は、原因候補を絞るためです。複数の引数を同時に書き換えると、どの変更で直ったのか分かりません。まず「処理が実行されたか」「クエリが0件か」「出力側の問題か」を分けます。

よくある原因一覧

よくある原因は、投稿タイプや公開状態の見落とし、存在しないページ番号、除外しすぎ、分類・メタ・日付・検索条件の不一致です。次の順番で、単純な原因から確認します。

最初に最小構成で確認する

原因を探すときは、まず条件を削ったWP_Queryを作ります。カテゴリー、タグ、カスタムフィールド、日付条件、検索語、並び順などは一度外し、公開済みの通常投稿を1件取得できるかを確認します。

元のコードと同じテンプレート、同じフック、できるだけ同じ表示位置で置き換えてください。別ページで動いただけでは、元の実行場所に問題がないとは判断できません。本番環境で試す場合は作業後に必ず削除し、可能なら検証環境で確認します。

次のコードは、通常の投稿を1件だけ取得して、IDとタイトルを表示する最小例です。複雑な条件を疑う前に、このコードで投稿が返るかを確認します。

$args = [   'post_type'      => 'post',   'post_status'    => 'publish',   'posts_per_page' => 1,]; $check_query = new WP_Query( $args ); if ( $check_query->have_posts() ) {   while ( $check_query->have_posts() ) {      $check_query->the_post();       echo '<p>WP_Query確認結果: ';      echo esc_html( get_the_ID() );      echo ' / ';      echo esc_html( get_the_title() );      echo '</p>';   }} else {   echo '投稿が見つかりませんでした。';} wp_reset_postdata();

このコードは、通常投稿、公開済み、1件だけに条件を絞っています。post_statusをpublishへ固定したのは、ログイン状態や管理画面かどうかで取得対象が変わる余地を減らすためです。問題が起きているのと同じ場所で1件表示されたなら、その場所では基本的なWP_Queryとループが動いています。

反対に、この最小例でも表示されない場合は、公開済みの通常投稿が存在するかを先に確認します。そのうえで、テンプレート未実行、PHPエラー、投稿状態、または別処理の影響を疑います。

原因別に条件と出力を切り分ける

症状が絞れている場合は、カスタム投稿、カテゴリー、meta_query、ページネーションのどこに問題があるかを分けて確認します。

あわせて読みたいカスタム投稿の確認順記事を読む

あわせて読みたいカテゴリー絞り込みの確認順記事を読む

あわせて読みたいmeta_queryのチェックリスト記事を読む

あわせて読みたいページネーションが動かない原因記事を読む

単純な条件で投稿が返ることを確認できたら、実際のコードへ条件を戻します。ここからは、取得対象、絞り込み、ループ、外部処理の順に見ていきます。

post_typeとpost_statusを確認する

最小構成で表示されないときにまず見るのは、post_type と post_status です。WordPressの投稿はすべて同じように見えても、通常投稿、固定ページ、カスタム投稿、添付ファイルなどで投稿タイプが分かれています。

たとえば説明用のカスタム投稿タイプ event を表示したいのに、post_type が post のままだと、イベント投稿は取得されません。実装時は event を、実際に登録されている投稿タイプスラッグへ置き換えます。

post、page、any、カスタム投稿タイプの違いを整理する必要がある場合は、post_typeの指定方法で取得対象から確認してください。

公式リファレンスでは、WP_Queryのpost_statusはpublishが基本ですが、ログイン状態や実行場所によって非公開・保護状態が加わる場合があります。公開画面と同じ条件を確かめたい時はpublishを明示します。添付ファイルは通常投稿と扱いが違うため、attachmentを取得する場合はinheritなどの状態も確認してください。

カスタム投稿が出ない時は、管理画面の表示名ではなく、登録時の投稿タイプスラッグを確認します。

件数・ページ位置・ID条件を確認する

取得対象が正しくても、ページ位置やID条件で対象を飛ばしすぎると0件になります。変数を渡している場合は、実際の値と型も確認してください。

posts_per_page に0を指定しても、0件になるとは限りません。現在のWordPressでは空の値として扱われ、サイトの表示件数設定へ補正される場合があります。また、-1 は全件取得です。0件の原因と決めつけず、実行時の値と上書き処理を確認します。

post__in へ空配列を渡しても「0件」にはならず、すべての投稿が返る場合があります。対象IDがないときはWP_Query自体を実行しないなど、クエリの前に分岐してください。

tax_queryやmeta_queryを一度外す

最小構成では表示されるのに、条件を足すと表示されない場合は、追加した絞り込み条件を疑います。特に tax_query と meta_query は、少し条件がズレるだけで0件になりやすい部分です。

tax_query はいったん全体を外します。それで投稿が返るなら、まず1つの条件だけを戻し、taxonomy、field、terms、operatorを確認します。管理画面の表示名と実際のタクソノミー名が違う場合があるため、複数条件のrelationは最後に戻してください。

meta_query も一度外し、1つの条件だけを戻します。メタキー、実際の保存値、compare、typeを確認し、複数条件のrelationは最後に戻します。数値を文字列として比較したり、ACFの表示名と保存用フィールド名を取り違えたりすると、想定どおりに絞り込めません。

配列の形から確認したいときは、tax_queryの基本とmeta_queryの基本を別々に確認します。まず1条件だけで期待する投稿が返る状態を作ってください。

さらに、date_query、検索語s、投稿者・親子関係などの追加条件も一度外します。最小構成へ1条件ずつ戻せば、どの指定を足したときに0件になるかを特定できます。

ループと出力側も確認する

クエリ条件に問題がないのに画面に出ない場合は、ループと出力側を確認します。WP_Queryでは have_posts() で投稿があるかを確認し、the_post() で1件ずつ投稿データをセットしてから、get_the_title() などのテンプレートタグを使います。

よくあるのは、WP_Query のインスタンスではなく、グローバル側の have_posts() を見てしまうケースです。サブループでは、作成した変数に対して have_posts() と the_post() を呼び出す必要があります。

have_posts() がtrueなのに見えない場合、WP_Queryは投稿を取得できています。returnや条件分岐で処理を抜けていないか、HTMLやCSSで非表示になっていないかも確認してください。

wp_reset_postdata() の不足は、直前のWP_Queryが0件になる原因ではありません。独自ループ後のタイトルや本文が別投稿を参照する場合に、末尾でメインクエリの投稿データへ戻しているかを確認します。

別の処理でクエリが変わっていないか確認する

コード上は正しく見えるのに表示されない場合、pre_get_posts などのフック、プラグイン、テーマ内の共通処理でクエリ条件が変更されていることがあります。対象を絞らずに登録された処理は、独自WP_Queryにも影響する可能性があります。

pre_get_posts などの処理を検索し、渡された $query の is_main_query() などで対象が絞られているか確認します。独自WP_Queryだけかサイト全体にも起きるかを分け、検証環境で疑わしい処理を1つずつ外して結果を比較してください。

ここまで確認しても原因が分からない場合は、最小構成から post_type、post_status、ページ位置・ID、tax_query、meta_query、日付・検索条件の順に1つずつ戻します。複数条件を同時に戻さないことが、原因を特定する近道です。

公式資料で確認したいポイント

WP_Queryは指定できる引数が多いため、表示されない原因もひとつではありません。迷ったときは、該当する引数だけを公式リファレンスで確認します。

今回のようなトラブルでは、標準ループと post_type、post_status、tax_query、meta_query を分けて確認します。後続表示は wp_reset_postdata()、外部影響は pre_get_posts の資料が手掛かりになります。

最後は小さい条件から戻していく

WP_Queryで投稿が表示されないときは、まず実行場所とPHPエラーを確認し、同じ場所で最小構成を試します。投稿が返らなければ取得条件、返っているならループと出力、後続表示だけがおかしければ投稿データのリセットを確認します。