2026年5月27日

WordPressのアイキャッチ画像が表示されない問題を解決する方法

メディア・画像

はじめに

WordPressの投稿一覧や個別記事ページでアイキャッチ画像が表示されない・投稿編集画面の右サイドバーに「アイキャッチ画像」メタボックスが表示されない・the_post_thumbnail()を呼び出してもHTMLが出力されない・add_image_size()で追加したカスタムサイズの画像が生成されないといった問題は、テーマがpost-thumbnailsサポートを宣言していない・the_post_thumbnail()の前後に必要な条件チェックがない・画像リサイズが実行されていないことが原因です。

症状・原因

テーマのfunctions.phpにadd_theme_support('post-thumbnails')がない
アイキャッチ画像は設定されているがhas_post_thumbnail()のチェックを通過できていない
add_image_size()で追加したサイズはそれ以降にアップロードした画像にしか適用されない
カスタム投稿タイプがthumbnailをサポートしていない

解決手順

ステップ1：アイキャッチ画像の状態を診断する

# テーマのpost-thumbnailsサポートを確認
wp eval "
echo 'post-thumbnails support: '  . (current_theme_supports('post-thumbnails') ? 'yes' : 'NO') . PHP_EOL;

// 登録されている画像サイズを確認
\$sizes = wp_get_registered_image_subsizes();
foreach (\$sizes as \$name => \$size) {
    echo \$name . ': ' . \$size['width'] . 'x' . \$size['height'] . ' | ' . (\$size['crop'] ? 'crop' : 'scale') . PHP_EOL;
}
"

# 特定の投稿のアイキャッチ画像を確認
wp eval "
\$post_id = 1;
echo 'has_post_thumbnail: ' . (has_post_thumbnail(\$post_id) ? 'true' : 'false') . PHP_EOL;
echo 'thumbnail ID: '       . get_post_thumbnail_id(\$post_id) . PHP_EOL;
echo 'thumbnail URL: '      . get_the_post_thumbnail_url(\$post_id, 'thumbnail') . PHP_EOL;
"

# カスタム投稿タイプのthumbnailサポートを確認
wp eval "
\$post_types = get_post_types(['public' => true], 'objects');
foreach (\$post_types as \$pt) {
    echo \$pt->name . ': thumbnail = ' . (post_type_supports(\$pt->name, 'thumbnail') ? 'yes' : 'no') . PHP_EOL;
}
"

ステップ2：テーマにpost-thumbnailsサポートを追加する

// functions.php: アイキャッチ画像のサポートを追加
add_action('after_setup_theme', function(): void {
    // 全投稿タイプでアイキャッチ画像を有効化
    add_theme_support('post-thumbnails');

    // 特定の投稿タイプのみ有効化する場合
    // add_theme_support('post-thumbnails', ['post', 'product']);

    // カスタム画像サイズを追加
    add_image_size('hero',        1200, 600, true);   // 1200x600 クロップ
    add_image_size('card',        400,  300, true);   // 400x300 クロップ
    add_image_size('thumbnail-lg', 300, 300, true);   // 300x300 クロップ
    add_image_size('wide',        800,  0,   false);  // 幅800px 縦比例
});

// テンプレートファイル: アイキャッチ画像を表示する正しい方法
<?php if (has_post_thumbnail()) : ?>
    <div class="post-thumbnail">
        <?php
        the_post_thumbnail('card', [
            'class'   => 'post-thumbnail-img',
            'loading' => 'lazy',
            'alt'     => get_the_title(),
        ]);
        ?>
    </div>
<?php endif; ?>

ステップ3：既存画像をカスタムサイズに再生成する

# 既存の全画像を全サイズで再生成
wp media regenerate --yes

# 特定のカスタムサイズのみ再生成
wp media regenerate --image-size=card --yes

# 特定の投稿の添付画像のみ再生成
wp media regenerate 123 456 789 --yes

# 再生成の進捗を確認しながら実行
wp media regenerate --yes --verbose

// functions.php: 画像サイズをメディアライブラリに表示する
add_filter('image_size_names_choose', function(array $sizes): array {
    return array_merge($sizes, [
        'hero'         => 'ヒーロー画像 (1200x600)',
        'card'         => 'カード画像 (400x300)',
        'thumbnail-lg' => '大サムネイル (300x300)',
        'wide'         => 'ワイド (800px幅)',
    ]);
});

ステップ4：アイキャッチ画像のフォールバックを設定する

// functions.php: アイキャッチ画像がない場合のフォールバック
function get_post_thumbnail_with_fallback(
    int    $post_id   = 0,
    string $size      = 'thumbnail',
    array  $attr      = []
): string {
    $post_id = $post_id ?: get_the_ID();

    if (has_post_thumbnail($post_id)) {
        return get_the_post_thumbnail($post_id, $size, $attr);
    }

    // 本文中の最初の画像をアイキャッチとして使用
    $post    = get_post($post_id);
    $content = $post->post_content ?? '';
    preg_match('/<img[^>]+src=["\']([^"\']+)["\'][^>]*>/i', $content, $matches);

    if (!empty($matches[1])) {
        $default_attr = [
            'class' => 'attachment-' . esc_attr($size) . ' size-' . esc_attr($size),
            'alt'   => esc_attr(get_the_title($post_id)),
        ];
        $attr = array_merge($default_attr, $attr);
        return '<img src="' . esc_url($matches[1]) . '"'
            . ' alt="' . esc_attr($attr['alt']) . '"'
            . ' class="' . esc_attr($attr['class']) . '">';
    }

    // デフォルト画像を使用
    $default_image = get_template_directory_uri() . '/images/no-image.jpg';
    return '<img src="' . esc_url($default_image) . '"'
        . ' alt="' . esc_attr(get_the_title($post_id)) . '"'
        . ' class="no-thumbnail">';
}

ステップ5：OGP・Twitterカード用のアイキャッチ画像を設定する

// functions.php: アイキャッチ画像をOGP・SNS共有用に使用
add_action('wp_head', function(): void {
    if (!is_singular()) {
        return;
    }

    $post_id  = get_the_ID();
    $img_url  = '';
    $img_w    = 0;
    $img_h    = 0;

    if (has_post_thumbnail($post_id)) {
        $thumb_id = get_post_thumbnail_id($post_id);
        $img_data = wp_get_attachment_image_src($thumb_id, 'large');
        if ($img_data) {
            [$img_url, $img_w, $img_h] = $img_data;
        }
    }

    if (!$img_url) {
        $img_url = get_template_directory_uri() . '/images/ogp-default.jpg';
        $img_w   = 1200;
        $img_h   = 630;
    }

    echo '<meta property="og:image" content="'         . esc_url($img_url) . '">' . PHP_EOL;
    echo '<meta property="og:image:width" content="'   . esc_attr($img_w)  . '">' . PHP_EOL;
    echo '<meta property="og:image:height" content="'  . esc_attr($img_h)  . '">' . PHP_EOL;
    echo '<meta name="twitter:card" content="summary_large_image">'               . PHP_EOL;
    echo '<meta name="twitter:image" content="'        . esc_url($img_url) . '">' . PHP_EOL;
});

注意事項

add_image_size()で追加したカスタムサイズはそれ以降にアップロードした画像にのみ適用されます。既存の画像にはwp media regenerateコマンドで再生成が必要です。大量の画像がある場合は時間がかかります
the_post_thumbnail()はループ内でのみ使用してください。ループ外ではget_the_post_thumbnail($post_id)のように投稿IDを指定して使用します
画像の再生成はサーバーに負荷をかけます。本番環境では深夜など低負荷時間帯に実行するか、--limitオプションで分割して実行してください

まとめ

WordPressアイキャッチ画像非表示の解決は①current_theme_supports('post-thumbnails')で確認・has_post_thumbnail()でアイキャッチ画像の設定状態確認・カスタム投稿タイプのthumbnailサポート確認、②add_action('after_setup_theme')内でadd_theme_support('post-thumbnails')を追加・add_image_size()でカスタムサイズを定義・has_post_thumbnail()で条件チェックしてthe_post_thumbnail()を呼び出し、③wp media regenerate --yesで既存画像を全サイズ再生成・--image-size=で特定サイズのみ再生成・image_size_names_chooseフィルターでメディアライブラリに表示、④get_the_post_thumbnail()でアイキャッチ取得・本文中の画像をフォールバックとして使用・デフォルト画像のURLをフォールバック末尾に設定、⑤wp_get_attachment_image_src()でアイキャッチのURLと寸法を取得・OGP・Twitterカード用メタタグとしてwp_headフックで出力の手順で解決します。

Post Views: 17