WordPress 獲取頭像 get_avatar() 與自定義 Alt 標籤完整教學

前言

WordPress 內建 get_avatar() 從 Gravatar 取得使用者大頭貼，廣泛用於留言列表、作者資訊、側邊欄。本文完整解析參數、回傳值、常見用法，並示範如何透過 get_avatar filter 自定義 alt 屬性，提升 SEO 與無障礙存取。

get_avatar() 函數完整解析

函數原型

get_avatar( $id_or_email, $size = 96, $default = '', $alt = false )

參數說明

回傳值

• 成功：<img> 完整 HTML 字串
• 後台「設定 → 討論 → 顯示頭像」關閉時：false

常用範例

// 1. 留言迴圈中取得留言者頭像
echo get_avatar( $comment, 48 );

// 2. 文章迴圈中取得作者頭像
echo get_avatar( get_the_author_meta('ID'), 64 );

// 3. 指定 Email 取得頭像（自訂 alt）
echo get_avatar( 'user@example.com', 32, '', '作者大頭貼' );

// 4. 使用預設頭像類型（Identicon 几何圖案）
echo get_avatar( $user_id, 80, 'identicon' );

自定義頭像 Alt 標籤 — 提升 SEO 與無障礙

問題：預設 alt 為空

Gravatar 回傳的 <img> 預設 alt=''，搜尋引擎無法理解圖片內容，螢幕閱讀器也會跳過。

方案一：統一替換為固定文字

/**
 * 統一設定所有頭像 alt = "Gravatar 頭像"
 */
add_filter('get_avatar', function($avatar) {
    $alt = 'Gravatar 頭像';
    $before = strpos($avatar, "alt='");
    $after = strpos($avatar, "'", $before + 5);
    if ($before !== false && $after !== false) {
        $alt = esc_attr($alt);
        return substr($avatar, 0, $before + 5) . $alt . substr($avatar, $after);
    }
    return $avatar;
});

方案二：依使用者身分區分（作者 vs 訪客）

/**
 * 依 $id_or_email 判斷：作者顯示「站長頭像」，訪客顯示「訪客頭像」
 * 注意：filter 優先度 10, 接受 2 參數
 */
add_filter('get_avatar', function($avatar, $id_or_email) {
    // 判斷是否為站長 (ID=1 或特定 Email)
    $isAuthor = ($id_or_email === 1 || $id_or_email === 'admin@example.com');
    $alt = $isAuthor ? '站長 Gravatar 頭像' : '訪客 Gravatar 頭像';

    $before = strpos($avatar, "alt='");
    $after = strpos($avatar, "'", $before + 5);
    if ($before !== false && $after !== false) {
        $alt = esc_attr($alt);
        return substr($avatar, 0, $before + 5) . $alt . substr($avatar, $after);
    }
    return $avatar;
}, 10, 2);

方案三：若已手動設定 alt 則保留，否則補上預設值

/**
 * 保留手動指定的 alt (get_avatar 第4參數)，未指定才補上預設
 * filter 接受 5 參數
 */
add_filter('get_avatar', function($avatar, $id_or_email, $size, $default, $alt) {
    if (!empty($alt)) return $avatar; // 已有自訂 alt，不覆蓋

    $alt = 'Gravatar 頭像';
    $before = strpos($avatar, "alt='");
    $after = strpos($avatar, "'", $before + 5);
    if ($before !== false && $after !== false) {
        $alt = esc_attr($alt);
        return substr($avatar, 0, $before + 5) . $alt . substr($avatar, $after);
    }
    return $avatar;
}, 10, 5);

進階：本地化頭像 / 替換 Gravatar 來源

替換為國內鏡像（加速載入）

add_filter('get_avatar', function($avatar) {
    return str_replace(
        ['secure.gravatar.com', 'www.gravatar.com', 'gravatar.com'],
        'cdn.v2ex.com/gravatar', // 或其他國內鏡像
        $avatar
    );
});

完全自訂頭像來源（如上傳至本地媒體庫）

add_filter('get_avatar', function($avatar, $id_or_email, $size, $default, $alt) {
    // 假設使用者 meta 'custom_avatar' 儲存本地圖片 ID
    $user_id = is_numeric($id_or_email) ? $id_or_email : 0;
    if (!$user_id && is_email($id_or_email)) {
        $user = get_user_by('email', $id_or_email);
        $user_id = $user ? $user->ID : 0;
    }
    if ($user_id) {
        $attachment_id = get_user_meta($user_id, 'custom_avatar', true);
        if ($attachment_id) {
            $url = wp_get_attachment_image_url($attachment_id, [$size, $size]);
            if ($url) {
                $alt = $alt ?: '使用者頭像';
                return sprintf(
                    '',
                    esc_url($url), $size, $size, esc_attr($alt), $size
                );
            }
        }
    }
    return $avatar;
}, 10, 5);

常見問題 FAQ

原始碼位置

小結

get_avatar() 是 WordPress 取得頭像的標準介面。善用 get_avatar filter 客製化 alt 屬性，不僅符合無障礙規範，也能讓搜尋引擎理解圖片語意。搭配本地化鏡像或自訂頭像來源，進一步提升載入速度與品牌一致性。