WordPress 縮略圖函式深度解析：the_post_thumbnail、get_the_post_thumbnail、set_post_thumbnail_size

the_post_thumbnail()：直接輸出完整 標籤

void the_post_thumbnail(string|array $size = 'post-thumbnail', string|array $attr = '')

• 必須在主迴圈內使用，自動取得當前文章 ID。
• $size：圖片尺寸關鍵字（thumbnail, medium, large, full）或陣列 [width, height]。預設 post-thumbnail 為主題設定的特色圖像尺寸。
• $attr：img 標籤屬性，陣列或查詢字串（如 ['class'=>'alignleft', 'alt'=>'標題']）。

// 基本用法
the_post_thumbnail('thumbnail', ['class' => 'img-fluid', 'alt' => get_the_title()]);

get_the_post_thumbnail()：回傳 HTML 字串，彈性更高

string get_the_post_thumbnail(int|WP_Post $post = null, string|array $size = 'post-thumbnail', string|array $attr = '')

• 可指定 $post（ID 或物件），不限主迴圈。
• 回傳完整 <img ...> 字串，可儲存變數、進一步處理、搭配短代碼輸出。
• 內部經過 post_thumbnail_html 過濾器。

$thumb = get_the_post_thumbnail(123, 'medium', ['class' => 'custom-class']);
echo '
' . $thumb . '
';

核心流程：wp_get_attachment_image

兩者最終皆呼叫 wp_get_attachment_image($attachment_id, $size, false, $attr)，流程：

1. 取得文章特色圖像 ID：get_post_thumbnail_id($post_id)。
2. 套用 post_thumbnail_size 過濾器決定最終尺寸。
3. 呼叫 wp_get_attachment_image 產生 srcset、sizes 等響應式屬性。
4. 觸發 begin_fetch_post_thumbnail_html / end_fetch_post_thumbnail_html 動作鉤子（供 JIT 過濾）。
5. 套用 post_thumbnail_html 過濾器回傳最終 HTML。

set_post_thumbnail_size()：主題註冊特色圖像尺寸

void set_post_thumbnail_size(int $width = 0, int $height = 0, bool $crop = false)

• 本質是 add_image_size('post-thumbnail', $width, $height, $crop) 的簡便封裝。
• 通常放在主題 functions.php 的 after_setup_theme 鉤子中。
• $crop = true：硬性裁切至指定比例；false：等比縮放（軟性裁切）。
• 寬或高設為 0 表示不限制該維度，自動等比縮放。

add_action('after_setup_theme', function() {
    add_theme_support('post-thumbnails');
    set_post_thumbnail_size(800, 450, true); // 16:9 硬性裁切
});

進階客製化

1. 替換預設特色圖像尺寸關鍵字

add_filter('post_thumbnail_size', function($size) {
    return is_single() ? 'large' : 'medium';
});

2. 修改輸出 HTML（加入 loading="lazy"）

add_filter('post_thumbnail_html', function($html, $post_id, $thumb_id, $size, $attr) {
    return str_replace('

3. 文章無特色圖像時顯示預設圖
add_filter('post_thumbnail_html', function($html, $post_id) {
    if (empty($html)) {
        return '';
    }
    return $html;
}, 10, 5);

常見問題與避坑

  
圖片模糊：上傳原圖尺寸小於註冊尺寸，WP 不會放大。確保原圖寬高 ≥ 註冊尺寸。
  
裁切位置不理想：WP 預設置中裁切。可用 image_resize_dimensions 過濾器或外掛（如 Simple Image Sizes）調整裁切錨點。
  
舊圖片不套用新尺寸：需重新產生縮圖，使用 Regenerate Thumbnails 外掛或 WP-CLI：wp media regenerate。
  
the_post_thumbnail() 在 the_content() 過濾器外無法運作：確保在主迴圈 while(have_posts()) 內呼叫。


總結
the_post_thumbnail 適合模板中直接輸出，get_the_post_thumbnail 適合需要字串操作的場景，set_post_thumbnail_size 是主題宣告特色圖像規格的標準方式。善用 post_thumbnail_html 過濾器可統一調整輸出屬性（lazy-loading、預設圖、結構化資料），避免在多處模板重複邏輯。