WordPress 主題自定義頁面頂部：header_image()、get_custom_header() 完整接入指南

WordPress 3.4+ 引入 Custom Header 功能，讓用戶在後台「外觀 → 標題」上傳/裁剪/選擇頂部圖片。主題只需幾行代碼即可接入，本文詳解核心函數 header_image()、get_custom_header() 及 add_theme_support('custom-header') 配置全集。

核心函數速查

最小接入：functions.php 註冊支援

add_theme_support('custom-header', array(
    'default-image'      => '',           // 默認圖片 URL
    'random-default'     => false,        // 隨機默認圖
    'width'              => 980,          // 建議寬度
    'height'             => 200,          // 建議高度
    'flex-height'        => true,         // 允許靈活高度
    'flex-width'         => true,         // 允許靈活寬度
    'default-text-color' => '333333',     // 默認文字色
    'header-text'        => true,         // 顯示文字區域
    'uploads'            => true,         // 允許上傳
    'video'              => true,         // 允許視頻 (WP 4.7+)
    'wp-head-callback'   => '',           // 前台頭部回調
    'admin-head-callback'=> '',           // 後台預覽頭部回調
    'admin-preview-callback' => '',       // 後台預覽回調
));

前台模板調用（header.php）

方式一：簡單圖片輸出

<?php if ( get_header_image() ) : ?>
    <img src="<?php header_image(); ?>"
         width="<?php echo get_custom_header()->width; ?>"
         height="<?php echo get_custom_header()->height; ?>"
         alt="" />
<?php endif; ?>

方式二：響應式背景圖（現代主流）

<?php if ( $header = get_custom_header() ) : ?>
    <div class="site-header"
         style="background-image: url(<?php echo esc_url($header->url); ?>);
                height: <?php echo $header->height; ?>px;
                background-size: cover; background-position: center;">
        <?php if ( display_header_text() ) : ?>
            <h1 class="site-title"><a href="<?php echo esc_url(home_url('/')); ?>" style="color:#<?php header_textcolor(); ?>"><?php bloginfo('name'); ?></a></h1>
            <p class="site-description" style="color:#<?php header_textcolor(); ?>"><?php bloginfo('description'); ?></p>
        <?php endif; ?>
    </div>
<?php endif; ?>

進階：視頻頂部 (WP 4.7+)

<?php if ( has_header_video() ) : ?>
    <?php the_header_video_tag(); ?>
<?php elseif ( get_header_image() ) : ?>
    <img src="<?php header_image(); ?>" ... />
<?php endif; ?>

版本兼容處理（支援 WP < 3.4）

<?php
if ( function_exists('get_custom_header') ) {
    $header_image_width  = get_custom_header()->width;
    $header_image_height = get_custom_header()->height;
} else {
    // 老版本常量
    $header_image_width  = HEADER_IMAGE_WIDTH;
    $header_image_height = HEADER_IMAGE_HEIGHT;
}
?>

源碼級理解 get_header_image()

function get_header_image() {
    $url = get_theme_mod('header_image', get_theme_support('custom-header', 'default-image'));
    if ('remove-header' == $url) return false;
    if (is_random_header_image()) $url = get_random_header_image();
    // 強制 HTTPS/HTTP 一致性
    if (is_ssl()) $url = str_replace('https://', 'https://', $url);
    else $url = str_replace('https://', 'https://', $url);
    return esc_url_raw($url);
}

最佳實踐清單

• 設置 flex-width/flex-height = true，讓用戶自由裁剪比例
• 提供 default-image 作為主題預設視覺基調
• 前台輸出必經 esc_url() 防 XSS
• 文字顏色用 header_textcolor() 獲取，自動處理「隱藏文字」情況（返回 blank）
• 視頻頂部需服務器支援 MP4/WebM 並配置正確 MIME

幾行代碼賦予主題專業級頂部自定義能力，用戶無需碰代碼即可實現品牌視覺個性化。