WP_Query トラブル用語count mismatch

WordPress の一覧で「10件表示のはずなのに9件しか出ない」「2ページ目が空になる」「ページリンクは3ページ分あるのに投稿が足りない」といった状態が起きることがあります。このような件数のズレを、この記事では count mismatch として整理します。

count mismatch は、見た目だけの問題ではありません。投稿を取得する条件、現在ページ番号、総ページ数、既存の main query、追加の custom query が関係します。原因を一度に探すのではなく、確認順を決めて切り分けることが大切です。

count mismatch は何を指す言葉か

count mismatch は、期待した件数と実際の件数が合わない状態です。WP_Query では、表示件数、取得件数、総件数、ページ数が別々に関係します。

たとえば、1ページ10件の一覧で9件しか出ない場合、posts_per_page だけでなく、除外条件、sticky posts、offset、ページネーション、投稿ステータスなどを確認する必要があります。

ここで大事なのは、「表示されている件数」と「クエリが持つ総ページ数」は別に確認することです。画面上のカード数だけ見ても、原因は分かりません。

特に custom query では、取得側の paged と、リンク側の paginate_links() の current / total がずれていることがあります。

最初に確認する順番

count mismatch を調べる時は、確認順を決めます。いきなり複雑な tax_query や meta_query を疑うのではなく、まず件数とページ番号の基本から見ます。

おすすめの順番は、posts_per_page、paged、offset、sticky posts、main query / custom query、pre_get_posts の影響です。基本条件から順番に確認すると、原因を見つけやすくなります。

この順番にすると、件数ズレの原因を広げすぎずに確認できます。特に offset はページネーションと組み合わせた時にズレの原因になりやすいため、早めに確認します。

また、既存のアーカイブ一覧を変えている場合と、独自 WP_Query で追加一覧を作っている場合では、確認する場所が変わります。どのクエリの件数がずれているのかを最初に見ます。

Builder での扱い

WP Query Builder では、count mismatch はエラー診断や注意表示として扱う想定です。生成コードで pagination を有効にする場合は、posts_per_page、paged、paginate_links()、max_num_pages をセットで出す必要があります。

また、offset を使う設定では、ページネーションとの相性に注意を出すべきです。初心者が「先頭1件を飛ばす」目的で offset を選ぶと、ページ数のズレにつながる可能性があります。

既存アーカイブを調整するモードでは、独自 WP_Query ではなく pre_get_posts を案内する場面もあります。追加一覧か既存一覧かを先に分けることが大切です。

使いどころ・避けどころと実践確認

画面の表示件数、post_count、found_posts、ページ総数のどれが違うのかを切り分ける時に使う観点です。

「件数が違う」を一括りにして、取得件数と総件数を同じ値として直そうとするのは避けます。

posts_per_page、offset、固定表示投稿、no_found_rows は別々の段階へ作用するため、最初に比較している数値の定義を固定します。

表示中の件数と検索に該当した総件数は別物なので、最初にどの数字を直したいのかを言葉にします。

同じクエリで post_count、found_posts、max_num_pages、表示された投稿IDを出力し、期待値との差が生じた段階を記録します。

実践記事で確認表示件数が合わないときの確認事項と対処法まとめ

4種類の件数を分けて確認する手順と、よくあるずれの原因を実例で追えます。

記事を読む →

WordPressの仕様で確認するポイント

公式資料では、WP_Query Class で posts_per_page、paged、offset などの引数を確認できます。現在ページ番号を取得する場合は get_query_var() を確認します。

既存の main query を調整する場合は pre_get_posts、ページ番号リンクを生成する場合は paginate_links() も合わせて確認します。

count mismatch は、WP_Query の表示件数、総件数、ページ数が期待とずれる状態です。原因は複数あるため、確認順を固定して切り分けます。

迷った時は、まず最小構成で1件ずつ取得し、posts_per_page、paged、offset、sticky posts、main query / custom query、pre_get_posts の順に確認します。