WordPress调用文章特色图片（缩略图）完整实操教程

时间：2026-08-13 22:36:16 来源：aliz.cn 作者：SKY 阅读：

WordPress 调用文章特色图片（缩略图）完整实操教程

原创实测，适用于 WordPress5.x‑6.x 版本。 WordPress 特色图片（Featured Image）是文章内置缩略图字段，后台编辑文章可以直接上传设置。很多主题二次开发时，经常遇到：调不出图片、尺寸不对、没有特色图片时空白、前台不显示等问题。本文整理全套调用代码。

一、前置条件：主题开启特色图片支持

如果你的主题没有开启特色图片，文章后台不会出现「特色图片」设置框。打开主题 functions.php，加入代码开启支持：
php
运行

//开启特色图片支持
add_theme_support( 'post-thumbnails' );

//自定义缩略图尺寸，名称：custom‑thumb，宽400，高260，true=强制裁剪
add_image_size( 'custom‑thumb', 400, 260, true );

保存后，后台文章编辑页面就会出现【设置特色图片】。

注意：旧上传图片不会自动生成新尺寸，需要安装插件「Regenerate Thumbnails」批量重生成缩略图。

二、基础调用方式（循环内使用，WP_Query /while 循环里面）

1、直接输出完整 img 标签（最简单）

php
运行

<?php if ( has_post_thumbnail() ) : ?>
    <?php the_post_thumbnail('custom‑thumb', ['class'=>'thumb-img','alt'=>get_the_title()]); ?>
<?php endif; ?>

参数说明：

custom‑thumb：图片尺寸名称，可以用系统自带：thumbnail(150x150)、medium、large、full原图
class：给图片加 css 类，方便写样式
alt：alt 属性用文章标题，利于 SEO

2、只获取图片 HTML 字符串，不直接输出

php
运行

<?php
if(has_post_thumbnail()){
    $thumb_html = get_the_post_thumbnail(get_the_ID(),'custom‑thumb',['class'=>'thumb-img']);
    echo $thumb_html;
}
?>

3、只拿图片地址 url（常用于 a 标签背景图）

php
运行

<?php
if(has_post_thumbnail()){
    $thumb_url = get_the_post_thumbnail_url(get_the_ID(),'custom‑thumb');
}
?>

<!-- 使用示例 -->
<div style="background:url(<?php echo $thumb_url;?>) no-repeat center;background‑size:cover;"></div>

三、无特色图片时输出默认占位图（高频需求）

列表页很多文章没有设置特色图片，不要空白，给一张默认图。

方案 A：在循环内完整示例（直接复制）

php
运行

<?php
$default_img = get_template_directory_uri().'/images/default‑thumb.jpg';//主题目录默认图
if ( has_post_thumbnail() ) {
    echo get_the_post_thumbnail( get_the_ID(), 'custom‑thumb', array( 'class' => 'thumb-img' ) );
} else {
    echo '<img src="'.$default_img.'" class="thumb-img" alt="'.esc_attr(get_the_title()).'">';
}
?>

把默认图片放到主题文件夹 images/default‑thumb.jpg。

方案 B：封装函数放到 functions.php，模板一行调用（推荐）

php
运行

/**
 * aliz.cn 获取文章缩略图，无图返回默认图
 * @param string $size 图片尺寸
 * @return string html img
 */
function aliz_get_post_thumb($size='medium'){
    $default = get_template_directory_uri().'/images/default‑thumb.jpg';
    if(has_post_thumbnail()){
        return get_the_post_thumbnail(get_the_ID(),$size,['class'=>'thumb-img','alt'=>esc_attr(get_the_title())]);
    }else{
        return '<img src="'.$default.'" class="thumb-img" alt="'.esc_attr(get_the_title()).'">';
    }
}

模板中直接调用：
php
运行

<?php echo aliz_get_post_thumb('custom‑thumb'); ?>

四、列表页完整实战示例（index.php/archive.php）

php
运行

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<div class="item">
    <div class="pic">
        <?php echo aliz_get_post_thumb('custom‑thumb'); ?>
    </div>
    <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
    <div class="excerpt"><?php the_excerpt(); ?></div>
</div>
<?php endwhile; endif; ?>

五、获取特色图片 alt、title、宽高元数据

php
运行

<?php
$post_id = get_the_ID();
if(has_post_thumbnail($post_id)){
    $thumb_id = get_post_thumbnail_id($post_id);
    $alt = get_post_meta($thumb_id, '_wp_attachment_image_alt', true);
}
?>

六、常见问题排查

调用后图片不显示、空白

确认 add_theme_support( 'post‑thumbnails' ); 已经写入 functions.php；
确认文章后台已经真正设置特色图片；
自定义图片尺寸，旧图片需要用 Regenerate Thumbnails 插件生成缩略图。

图片尺寸不对，总是输出原图很大

the_post_thumbnail 第二个参数必须写对尺寸名称，不能直接填数字；
add_image_size 第三个参数 true 开启裁剪，否则只是缩放不裁切。

特色图片在后台有，前台不输出

代码必须放在 WordPress 文章循环while(have_posts())内部；
循环外部调用必须传入文章 ID：get_the_post_thumbnail($post_id,'size')。

图片没有 alt 标签，不利于 SEO 调用的时候手动传入 alt 属性，不要依赖系统默认。

七、补充：WP_Query 自定义循环调用特色图片

php
运行

<?php
$args = array(
    'post_type'=>'post',
    'posts_per_page'=>10
);
$query = new WP_Query($args);
if($query->have_posts()){
    while($query->have_posts()){
        $query->the_post();
        echo aliz_get_post_thumb('custom‑thumb');
    }
    wp_reset_postdata();
}
?>