アイキャッチを設定したのに一覧でサムネイルが出ないとき｜画像以外のファイルも設定できてしまう仕組みと、1件だけ違う原因の絞り方

記事を公開したのに、一覧ページのサムネイルだけが空白のまま。管理画面を開くとアイキャッチはちゃんと設定されていて、プレビューまで表示される。それでもサイトには出ない——という相談がときどき来ます。

先に結論を書きます。

「設定できているのに出ない」ときは、キャッシュや設定を疑う前に、そのアイキャッチが本当に画像ファイルかどうかを確かめてください。 WordPressはメディアライブラリに入っているものであれば、PDFでも動画でもアイキャッチとして設定できてしまいます。しかも管理画面ではPDFのプレビューが描画されるため、更新した本人には「正しく設定できた」ようにしか見えません。

確認はREST APIでファイルの種類を1つ見るだけで済みます。ブラウザでURLを1本開くだけの作業です。

この記事で扱うのは次の4点です。

• なぜ画像でないファイルがアイキャッチに入ってしまうのか
• 「出ない」の原因を上から3ステップで絞る手順
• 1件だけ出ないときに、全記事を目視せず機械で点検する方法
• 同じ操作をされても壊れないようにする受け入れ側の作り

弊社graciautoは名古屋でホームページ制作とWEB運用支援を手掛けており、納品後にクライアント自身が記事を更新していくサイトを多く預かっています。この記事は、そうした支援先のサイトで実際に起きた事象と、記事全数を点検して得た実測をもとに書いています。サイト名は伏せています。

—

まず切り分ける：全部出ないのか、1件だけ出ないのか

原因を探しはじめる前に、この分岐だけ先に確定させてください。ここを飛ばすと、見る場所を間違えます。

• 全記事でサムネイルが出ない → テンプレート側の問題。一覧を描いているコードがアイキャッチを呼んでいないか、呼び方が違う
• 一部の記事だけ出ない → データ側の問題。その記事に設定されているものを見に行く

一覧全体が空白なら実装を疑ってよいのですが、1件だけ出ないときにテンプレートを読みはじめるのは時間の無駄です。 同じテンプレートが他の記事では正しく描けている以上、違いは記事側にしかありません。

「1件だけかどうか」は感覚ではなく数で押さえます。後述する一括点検を使えば、記事が何十本あっても数分で分かります。

—

画像でないファイルがアイキャッチに入る仕組み

一部の記事だけ出ない場合に、まず疑ってほしいのがこれです。

WordPressのアイキャッチ設定画面は、メディアライブラリの中身をファイルの種類で絞り込みません。PDFも動画も、アップロード済みであれば選択できてしまいます。

やっかいなのは、そこで警告が何も出ないことです。

• 管理画面はPDFのプレビューを描画する。更新した人には画像に見える
• 投稿の保存も普通に通る。「設定できました」以外の表示は出ない
• サイト側は指定されたURLを素直に <img> タグに入れて出力する
• ブラウザは .pdf を画像として描画できないので、そこが空白になる。ただしエラーメッセージは出ない

つまり、どの画面にも「間違っている」という表示が出ないまま、表示だけが静かに欠けるという状態になります。更新した人が気づけないのは当然で、操作ミスというより仕組み側の落とし穴です。

なぜPDFが混ざるのか

書き出し形式の選び間違いです。ブラウザで使うデザインツールは、ダウンロード時にPNG・JPG・PDF・動画を同じメニューから選ばせます。形式を意識せずに進めると、画像のつもりでPDFが手元に落ちてくることがあります。

実際に発生したケースでは、同じ日に同じ名前のPDFと動画ファイルの両方がメディアライブラリに上がっていました。デザインツールから続けて2つの形式で書き出し、そのままアップロードしたと考えるのが自然です。中身はどちらもアイキャッチのデザインそのもので、作った本人の作業は何も間違っていません。形式だけが違っていたわけです。

—

確認は3ステップ、上から順に

対象の記事が絞れたら、次の順で見ます。ブラウザのアドレスバーだけで完結します。

① そもそも設定されているか

https://サイトのURL/wp-json/wp/v2/posts/記事ID を開き、featured_media の値を見ます。ここが 0 なら未設定です。管理画面で設定したつもりが保存されていないケースはこれで分かります。

② 設定されているものが画像か

featured_media に入っていた番号を使って、https://サイトのURL/wp-json/wp/v2/media/その番号 を開きます。見るのは2か所です。

• mime_type が image/ で始まっているか。application/pdf や video/mp4 になっていれば、これが原因です
• media_details の width と height に数値が入っているか。画像でないファイルはここが空になります

この2つは連動しているので、どちらか一方を見れば足ります。幅と高さが空のアイキャッチは、まず表示されません。

③ ファイルそのものが届くか

source_url をブラウザで直接開きます。404なら、ファイルが消えているかパスがずれています。①②が正常でここだけ落ちているなら、移行やバックアップ復元でファイルの実体が欠けた可能性を見ます。

①②③のどれで止まったかで、直す場所が決まります。上から順に潰せば、キャッシュやプラグインを疑う場面はほとんど来ません。

—

1件だけかどうかは、全記事を機械で点検して確定させる

記事を1本ずつ開いて確認するやり方は、記事数が増えるほど現実的でなくなります。REST APIで一括点検してください。

手順は3つです。

1. 投稿一覧を取得し、各記事の featured_media を集める（_fields=id,title,featured_media を付けると軽くなります）
2. 集めた番号をまとめて /wp-json/wp/v2/media?include=番号1,番号2,... に渡し、1回のリクエストで全部引く
3. 返ってきた mime_type が image/ で始まらないものを抜き出す

実際にこの点検を記事29本のサイトで走らせたところ、該当したのは1件だけでした。残り28本はすべて image/png で、寸法も830×480にそろっていました。アイキャッチが未設定の記事は0本です。

この「1件だけ」という結果自体に価値があります。サイト側の実装を疑わなくてよくなるからです。 全記事で崩れているならテンプレートかテーマの問題ですが、28本が正常に出ている以上、直すべきはその1件のデータだけだと確定します。調査範囲が一気に狭まります。

同じ点検は、記事を移行した直後にも通しておくと効きます。移行では本文が正しく運べていてもアイキャッチの紐付けだけが落ちることがあり、全数の featured_media を見れば数分で確認できます。

—

直し方は2つある。どちらを選ぶかは運用で決める

原因が特定できたあと、選択肢は2つです。

A. 制作側がデータを差し替える — 正しい形式の画像をアップロードし直し、アイキャッチを付け替える。作業は5分で終わります。

B. 更新している人に、正しい形式で上げ直してもらう — 連絡と反映待ちの時間がかかります。

速いのはAですが、クライアント自身が日常的に記事を更新しているサイトなら、Bを選ぶほうが結果的に事故が減ります。 制作側が黙って直すと、同じ書き出し方が繰り返され、同じ問い合わせが毎回発生するためです。実際に発生したケースでも、こちらでデータを差し替えるのではなく、正しい形式で再アップロードしてもらう形をとりました。

このとき、「PDFはアイキャッチに使えません」とだけ伝えても再発します。書き出し形式と寸法を具体的に指定して渡してください。 「PNGで、横830×縦480」のように数字まで決めておくと、迷う余地がなくなります。

元のPDFしか手元にない場合

デザインの元データが残っていないこともあります。その場合はPDFから画像を取り出すことになりますが、変換方法によって解像度が大きく変わる点に注意してください。

紙面サイズをそのまま画素数に換算する方式で変換すると、実際に必要な解像度よりかなり小さい画像しか得られません。同じPDFから取り出したときに、方式の違いで623×360と1660×959という差が出たことがあります。前者では一覧に並べた時点で粗さが見えます。解像度を指定して書き出せる方式を使い、書き出したあとに実寸を確認してください。

—

恒久対策は「間違った操作をされても壊れない」受け皿

ここまでは起きたあとの話です。同じことを繰り返さない作りにしておくほうが確実です。

対策は、表示する側にガードを1つ置くことです。

• アイキャッチを読み込むとき、mime_type が image/ で始まるかを確認する
• 始まらなければそのアイキャッチは無視して、代替画像を出す
• アイキャッチが未設定のときも、同じ代替画像を出す

こうしておくと、PDFを設定されても一覧は崩れません。空白が並ぶ代わりに、既定の画像がおとなしく入るだけです。表示が壊れないので、更新した人が困る場面も消えます。

クライアントが自分で更新するサイトでは、操作を禁止するより、壊れない受け皿を先に作るほうが確実です。 操作手順の説明は担当者が変われば失われますが、コード側のガードは残ります。研修より構造で守る、という考え方です。

同じ発想で、アップロードの入口側に軽量化の処理を1本入れておくのも有効です。書き出したままの画像は想像以上に重く、あるサイトでは記事アイキャッチの上位6枚だけで約1.77MB、1枚449KBや427KBという状態になっていました。アップロード時に自動で変換する経路を通すと、311KBの画像が150KB程度まで落ちます。表示速度の対策として後からまとめてやるより、入口で毎回効かせるほうが手間がかかりません。

—

ついでに見ておきたい「壊れてはいないが効いていない」状態

アイキャッチは、出てさえいれば良いというものでもありません。点検のついでに次も見ておくと、一覧ページの質が上がります。

同じサイトで記事とは別の投稿群57本を調べたところ、実際に使われている画像は5枚だけでした。カテゴリごとに共通画像を割り当てていたためで、同じカテゴリの11本はすべて同じ写真が並んでいる状態です。

これは不具合ではありません。設定は正しく、表示も出ています。ただ、一覧として見たときに情報量がゼロに近い。11件並んだカードが全部同じ絵なら、訪問者はどれを読むか選べません。

すべてに個別の写真を用意するのが難しいなら、写真をやめて図版やパターンに切り替えるほうが、一覧としては機能します。「アイキャッチが出ているか」だけでなく、「一覧に並べたときに区別がつくか」まで見て初めて点検が終わります。

—

まとめ

アイキャッチが表示されないときの手順を整理します。

• 全記事で出ないのか、一部だけかを先に確定させる。 全部ならテンプレート側、一部ならデータ側。1件だけでテンプレートを読みはじめない
• 一部だけなら、そのアイキャッチが画像かどうかを疑う。 WordPressはPDFや動画もアイキャッチに設定でき、管理画面ではプレビューまで出るため、操作した人には正しく見える
• 確認はmime_typeがimage/で始まるか、media_detailsの幅と高さが入っているかの2点。エラーは出ないので、自分で見に行くしかない
• 全記事の点検はRESTで一括に。 featured_mediaを集めてincludeでまとめて引けば、数十本でも数分で終わる。「1件だけ」と確定できると調査範囲が一気に狭まる
• クライアントが更新するサイトでは、制作側が黙って直さず、書き出し形式と寸法を数字で指定して上げ直してもらう
• 恒久対策は受け入れ側のガード。画像でなければ代替画像に切り替える判定をひとつ足すだけで、同じ操作をされても表示は壊れない

表示が欠けているのにエラーが出ない不具合は、原因が分かってしまえば5分の作業です。厄介なのは、気づくまでに時間がかかることのほうです。記事を追加したら一覧ページを1回開いて見る——それだけで、この種の不具合はほぼ当日中に見つかります。

ホームページの運用や、納品後にクライアント側で更新できる仕組みづくりでお困りでしたら、お気軽にご相談ください。