add_image_size を追加しても反映されない原因と対処｜サムネイル再生成の方法

結論

add_image_size() で追加したサイズの画像ファイルは、画像を「アップロードしたとき」に生成されます。すでにアップロード済みの画像には、新しいサイズのファイルは作られません。反映させるには、既存画像のサムネイルを再生成します。

• WP-CLI が使える: wp media regenerate --yes（特定サイズだけなら --image_size=ks_card）
• 管理画面で行いたい: 再生成系のプラグインを使う
• コードで行いたい: wp_generate_attachment_metadata() と wp_update_attachment_metadata() を呼ぶ

公式リファレンスにも、新しいカスタムサイズには既存画像の再生成が必要で、WP-CLI の wp media regenerate や再生成プラグインを使うよう記載されています。また、元画像と同じかそれより小さいサイズは作られない、削除したサイズの既存ファイルは自動で消えない、という注意もあります。

原因・仕組み

画像をアップロードすると、WordPress は登録済みの画像サイズごとにファイルを作り、その情報を添付ファイルのメタデータ（_wp_attachment_metadata）に保存します。add_image_size() は「今後作るサイズの登録」であり、既存のメタデータを書き換えません。そのため、既存画像で ks_card を要求すると、該当ファイルがなく、元のサイズの画像が返ります。

$crop の指定は、false（比例縮小）、true（中央から切り抜き）、array( 'left', 'top' ) のような位置指定の3種類です。false だと、指定した幅と高さに収まるように縮小され、指定した寸法ぴったりにならないことがあります。

手順（サンプルコード）

// functions.php または、after_setup_theme で登録
add_action( 'after_setup_theme', function () {
    add_theme_support( 'post-thumbnails' );
    add_image_size( 'ks_card', 400, 300, true ); // 400x300 に切り抜き
} );

// 1枚だけコードで再生成する例（管理者のみ実行する処理に組み込む）
function ks_regenerate_one( $attachment_id ) {
    require_once ABSPATH . 'wp-admin/includes/image.php';
    $file = get_attached_file( $attachment_id );
    if ( ! $file || ! file_exists( $file ) ) {
        return new WP_Error( 'ks_nofile', '元ファイルがありません' );
    }
    $meta = wp_generate_attachment_metadata( $attachment_id, $file );
    if ( empty( $meta ) ) {
        return new WP_Error( 'ks_nometa', 'メタデータを生成できませんでした' );
    }
    wp_update_attachment_metadata( $attachment_id, $meta );
    return true;
}

表示は、wp_get_attachment_image_src( $id, 'ks_card' ) で [ URL, 幅, 高さ, 中間サイズ（リサイズ済み）の画像かどうか ] が得られます（4番目は公式リファレンスの is_intermediate。切り抜きの有無ではありません）。投稿のアイキャッチなら the_post_thumbnail( 'ks_card' ) です（wp_get_attachment_image_src() の使い方｜説明・引数・注意点）。

動作確認（検証環境と結果）

WordPress 7.1.2、PHP 8.2.12（GD 拡張を有効化: php -d extension=gd run.php ...）、MariaDB 10.4.32 で実行しました。1200×800 の JPEG を media_handle_sideload() で取り込んで検証しています（ログは tests フォルダ）。

• アップロード直後の sizes: medium(300x200)、large(1024x683)、thumbnail(150x150)、medium_large(768x512)。
• add_image_size( 'ks_card', 400, 300, true ) を呼んだ直後: sizes に変化なし。
• この時点で wp_get_attachment_image_src( $id, 'ks_card' ) を呼ぶと、元画像のURLと 400x267（元画像の比率で縮小した値）、4番目の値は false が返った。
• wp_generate_attachment_metadata() と wp_update_attachment_metadata() で再生成すると、sizes に ks_card(400x300) が追加され、同じ呼び出しで ...-400x300.jpg、400x300、4番目の値は true になった。
• 元画像（1200×800）より大きい ks_huge（3000×2000）を追加して再生成しても、sizes に追加されなかった。

WP-CLI の wp media regenerate と、再生成プラグインは、この環境では実行していません。

add_image_size を追加しても反映されない原因と対処の注意点

• 再生成は、画像枚数が多いと時間とサーバー負荷がかかります。バックアップを取り、アクセスの少ない時間帯に、WP-CLI で実行するのが安全です。
• 再生成しても、古い名前のサイズのファイルは削除されません。ディスクを整理したい場合は、専用の処理が必要です。
• 画像サイズ名は、他のプラグインと重複しないよう接頭辞を付けます。
• 比率の異なる画像を crop = true で切り抜くと、被写体が切れることがあります。位置指定の配列で調整します。
• 管理画面のメディア選択肢にサイズ名を出したい場合は、image_size_names_choose フィルターを使います（本検証では実行していません）。

add_image_size を追加しても反映されない原因と対処でよくあるミス

• add_image_size() を追加しただけで、既存の記事の画像が変わると期待する。
• 元画像が小さく、指定サイズ以上のファイルが作られないことに気づかない。
• 実際のテンプレートが別のサイズ名（'large' など）を指していて、追加したサイズを使っていない。
• add_theme_support( 'post-thumbnails' ) を忘れ、アイキャッチ自体が使えない。
• 再生成前にバックアップを取らない。

add_image_size を追加しても反映されない原因と対処のチェックリスト

• サイトの画像が、再生成の対象か。
• 追加したサイズ名とテンプレートの指定が一致しているか。
• 元画像が指定サイズより大きいか。
• バックアップを取ったか。
• 再生成後、表示とファイル（wp-content/uploads）を確認したか。

add_image_size を追加しても反映されない原因と対処のFAQ（よくある質問）

Q. 再生成すると、画像の URL は変わりますか。
A. 元画像の URL は変わりません。サイズ別のファイル名（-400x300 が付くもの）が増えます。本文に埋め込み済みの画像は、再生成だけでは差し替わらない場合があります。

Q. サイズを削除するには？
A. remove_image_size() で今後の生成を止められます（remove_image_size() の使い方｜説明・引数・注意点）。既存ファイルは別途削除が必要です。

Q. 画像が荒く見えます。
A. 表示サイズより小さいファイルが使われている可能性があります。Retina 向けには、2倍のサイズも用意します。

add_image_size を追加しても反映されない原因と対処の関連項目

• add_image_size() の使い方｜説明・引数・注意点
• wp_get_attachment_image_src() の使い方｜説明・引数・注意点
• wp_generate_attachment_metadata() の使い方｜説明・引数・注意点
• wp_update_attachment_metadata() の使い方｜説明・引数・注意点
• set_post_thumbnail_size() の使い方｜説明・引数・注意点