【WordPress】アイキャッチ未設定時にデフォルト画像を表示する方法｜post_thumbnail_htmlフィルター

2023.12.08

アイキャッチ画像を設定していない投稿があると、一覧やSNSシェア時の見た目が寂しくなります。この記事では、アイキャッチが未設定のときだけデフォルト画像を表示する正しい実装方法を解説します。

この記事でわかること

  • post_thumbnail_html フィルターで自然に差し込む方法（推奨）
  • テンプレートで直接分岐する方法
  • 古い実装（add_action('wp', ...)）のタイミング問題
スポンサーリンク

post_thumbnail_html フィルターで差し込む（推奨）

post_thumbnail_html フィルターは、the_post_thumbnail() / get_the_post_thumbnail() の戻り値そのものに介入できます。アイキャッチが未設定のときだけデフォルト画像のHTMLに差し替えれば、呼び出した場所にそのまま自然に表示されます。子テーマの functions.php に追加してください。

functions.php：未設定時にデフォルト画像へ差し替える
add_filter('post_thumbnail_html', function ($html, $post_id, $post_thumbnail_id, $size, $attr) {
  if ($html) {
    return $html; // アイキャッチが設定済みならそのまま
  }

  $default_url = get_template_directory_uri() . '/images/default-featured-image.jpg';
  return '<img src="' . esc_url($default_url) . '" alt="" class="attachment-post-thumbnail">';
}, 10, 5);
呼び出し側は今までどおりでよい
テンプレート側はいつもと同じ the_post_thumbnail() のままで構いません。アイキャッチの有無を意識せず、常にこの1行を呼ぶだけで設定済みなら本来の画像、未設定ならデフォルト画像が出力されます。
テンプレート：呼び出し側はシンプルなまま
if (have_posts()) {
  while (have_posts()) {
    the_post();
    the_post_thumbnail('medium'); // 未設定でも自動でデフォルト画像になる
  }
}

古い実装（add_action(‘wp’, …)）は避ける

wpフックでのecho出力はタイミングが早すぎる
add_action('wp', function () { if (!has_post_thumbnail()) { echo '<img ...>'; } }); という実装をよく見かけますが、wp アクションはHTML出力が始まる前（get_header() より前）に発火するため、ここで echo した画像は投稿の表示位置とは無関係な、ページの先頭（<!DOCTYPE html> より前）に出力されてしまいます。さらに、この関数をテンプレート内でも直接呼び出すと、画像が2回出力されます。テンプレートで表示位置を制御したいだけなら、次のようにループ内で条件分岐するのが確実です（ただし post_thumbnail_html フィルターの方がシンプルで安全です）。
テンプレート：ループ内で直接分岐する場合（代替案）
if (has_post_thumbnail()) {
  the_post_thumbnail('medium');
} else {
  $default_url = get_template_directory_uri() . '/images/default-featured-image.jpg';
  echo '<img src="' . esc_url($default_url) . '" alt="">';
}

関連するアイキャッチのカスタマイズ

よくある質問（FAQ）

Qアイキャッチ未設定の場合にデフォルト画像を表示する一番簡単な方法は？
Apost_thumbnail_html フィルターで the_post_thumbnail() の戻り値が空のときだけデフォルト画像のHTMLを返すようにします。テンプレート側のコードを変える必要がなく、記事全体に一括で適用できます。
Qデフォルト画像をメディアライブラリの画像から選べるようにするには？
Aadd_option() でデフォルト画像のURL（または添付ファイルID）を保存するオプションを作り、カスタマイザーやテーマ設定画面からメディアアップローダーで選択できるようにします。取得したURLを post_thumbnail_html フィルター内で使えば、管理画面から差し替え可能なデフォルト画像になります。
Qカテゴリーごとに違うデフォルト画像を出したいです。
Apost_thumbnail_html フィルター内で get_the_category() を使い、カテゴリーに応じて返すデフォルト画像のURLを切り替えます。詳しい実装はカテゴリーごとに異なるデフォルトのサムネイル画像を表示する方法を参照してください。

まとめ

  • 推奨：post_thumbnail_html フィルターで戻り値を差し替える
  • 呼び出し側：the_post_thumbnail() はそのままでよい
  • 避ける：add_action('wp', ...) でのecho（出力位置がずれる・二重出力の危険）
  • 代替：テンプレート内で has_post_thumbnail() の条件分岐でも可

post_thumbnail_html フィルターを使えば、表示位置のずれや二重出力を気にせず、安全にデフォルト画像を用意できます。