【WordPress】アイキャッチ画像のURLを取得する方法｜get_the_post_thumbnail_urlと安全な出力

2023.11.16

アイキャッチ画像を<img>タグやOGPのog:imageに使いたいとき、画像そのものではなくURLだけを取得したい場面があります。この記事では get_the_post_thumbnail_url() を使った取得方法と、安全な出力・未設定時の対処まで解説します。

この記事でわかること

  • get_the_post_thumbnail_url() でURLを取得する
  • サイズ（thumbnail・medium・large・full）を指定する
  • esc_url() での安全な出力と未設定時のガード
  • アイキャッチが内部でどう保存されているか
スポンサーリンク

アイキャッチ画像のURLを取得する

get_the_post_thumbnail_url() に投稿IDを渡すと、URLを取得できます。出力時は esc_url() でエスケープしてください。

PHP：アイキャッチ画像のURLを取得
$post_id = get_the_ID();
$thumbnail_url = get_the_post_thumbnail_url($post_id);

echo esc_url($thumbnail_url);
アイキャッチが未設定だと false が返る
アイキャッチを設定していない投稿では get_the_post_thumbnail_url() は false を返します。そのまま<img src="">のように出力すると壊れた画像タグになるため、取得できたときだけ出力するガードを入れましょう。
PHP：未設定時のガード付き
if ($thumbnail_url) {
  echo '<img src="' . esc_url($thumbnail_url) . '" alt="">';
}

アイキャッチが設定されていない場合に代わりの画像を出したい場合はアイキャッチ画像が設定されていない場合にデフォルトの画像を表示する方法を参照してください。

特定のサイズのURLを取得する

第2引数にサイズ名を渡すと、そのサイズのURLを取得できます。組み込みサイズは thumbnail（150）・medium（300）・large（1024）・full（オリジナル）です。

PHP：サイズを指定して取得
$thumbnail_url = get_the_post_thumbnail_url($post_id, 'medium');
echo esc_url($thumbnail_url);

内部ではどう保存されているか

get_the_post_thumbnail_url() は、内部で投稿の _thumbnail_id（WordPressがアイキャッチ管理に使うメタキー）から添付ファイルIDを取得し、そのURLを返しています。仕組みを理解しておくと、他の関数と組み合わせるときに役立ちます。

PHP：_thumbnail_id から手動でURLを組み立てる（内部の仕組み）
$thumbnail_id = get_post_meta($post_id, '_thumbnail_id', true);

if ($thumbnail_id) {
  $thumbnail_url = wp_get_attachment_image_url($thumbnail_id, 'medium'); // サイズも指定できる
  echo esc_url($thumbnail_url);
}
「カスタムフィールド」ではなく内部メタキー
_thumbnail_id は、投稿者が入力するカスタムフィールドではなくWordPress自身がアイキャッチの管理に使う内部データです。通常の実装では、この生のメタキーを直接扱わず、get_the_post_thumbnail_url() を使うだけで十分です。あえて分解して扱う必要があるのは、カスタムのキャッシュ処理など特殊な要件がある場合に限られます。

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

よくある質問（FAQ）

Qアイキャッチ画像のURLを取得する関数を教えてください。
Aget_the_post_thumbnail_url($post_id, $size) でURLを取得します。例：$url = esc_url(get_the_post_thumbnail_url(get_the_ID(), "medium"));。<img>タグ全体が必要な場合は get_the_post_thumbnail() を使うと簡潔です。アイキャッチが未設定の場合は false が返るので、出力前に確認してください。
QアイキャッチのすべてのサイズのURLを取得するには？
Awp_get_attachment_image_srcset($attachment_id) でレスポンシブ対応のsrcset用URL一式を取得できます。登録済みサイズ名の一覧は get_intermediate_image_sizes() で取得し、各サイズのURLは wp_get_attachment_image_src($id, $size) で個別に取得できます。
QOGPのog:imageにアイキャッチ画像を使うには？
Awp_head アクション内でURLを取得し、esc_url() でエスケープしてmetaタグに出力します。$img = get_the_post_thumbnail_url(get_the_ID(), "large"); if ($img) { echo '<meta property="og:image" content="' . esc_url($img) . '">'; }。Yoast SEOなどのSEOプラグインを使っている場合は自動で設定されます。

まとめ

  • 基本：get_the_post_thumbnail_url($post_id, $size)
  • 出力：必ず esc_url() でエスケープする
  • 未設定時：false が返るため if ($thumbnail_url) でガードする
  • 内部：_thumbnail_id（WP内部メタ）を通常は直接扱う必要はない

取得したURLは esc_url() で必ずエスケープし、未設定の場合の表示も忘れずに用意しておきましょう。