一、the_post_thumbnail() 函数基础
函数签名
the_post_thumbnail( $size, $attr );
the_post_thumbnail( $size, $attr );
这个函数必须在主循环(The Loop)内使用,用于输出当前文章的特色图片(Featured Image)的完整 <img> 标签。如果要获取任意文章的缩略图 HTML 而非直接输出,用 get_the_post_thumbnail( $id, $size, $attr ) 代替。
参数一:$size(图片尺寸)
这是最核心的参数,接受字符串或数组两种形式。
1. 字符串形式(尺寸关键字)
WordPress 内置了以下几个关键字:
| 关键字 | 默认尺寸 | 说明 |
|---|---|---|
'thumbnail' |
150×150 | 缩略图,默认硬裁剪为精确尺寸 |
'medium' |
最大 300×300 | 中等尺寸,等比缩放,不硬裁 |
'medium_large' |
最大 768×0 | 中大型,只限宽度,高度不限 |
'large' |
最大 1024×1024 | 大尺寸,等比缩放 |
'full' |
原始尺寸 | 上传的原图,不做任何处理 |
'post-thumbnail' |
由主题定义 | 默认值,由 set_post_thumbnail_size() 设置 |
the_post_thumbnail(); // 默认 -> 'post-thumbnail'
the_post_thumbnail('thumbnail'); // 150×150(硬裁剪)
the_post_thumbnail('medium'); // 最大 300×300(等比)
the_post_thumbnail('medium_large'); // 最大 768×0
the_post_thumbnail('large'); // 最大 1024×1024(等比)
the_post_thumbnail('full'); // 原图
2. 数组形式(指定宽高)
the_post_thumbnail( array( 300, 300 ) );
the_post_thumbnail( array( 300, 300 ) );
这就是你觉得”很合适”的写法。它的行为是:
- WordPress 会在所有已生成的尺寸中,找到最接近 300×300 的那个版本来输出
- 它不会现场裁剪或生成新图,只是在已有尺寸里”挑一个最匹配的”
- 如果原图比 300×300 还小,则直接输出原图(不会放大)
关键理解:
array(300, 300)本质是”从已有尺寸中选最接近的”,而不是”强制生成一张 300×300 的图”。
3. 自定义尺寸关键字
通过 add_image_size() 注册的尺寸,也可以用字符串调用:
// functions.php 中注册
add_image_size( 'card-cover', 300, 300, true ); // 硬裁剪
// 模板中调用
the_post_thumbnail( 'card-cover' );
参数二:$attr(HTML 属性数组)
这是一个可选的关联数组,会被转换为 <img> 标签的 HTML 属性。
$attr = array(
'class' => 'my-image alignleft',
'id' => 'hero-thumb',
'data-src' => 'lazy-load-url',
'alt' => '自定义替代文本',
'title' => '图片标题',
);
the_post_thumbnail( 'medium', $attr );
输出效果:
<img width="300" height="200"
src="..."
class="my-image alignleft attachment-medium wp-post-image"
id="hero-thumb"
data-src="lazy-load-url"
alt="自定义替代文本"
title="图片标题" />
注意:
class属性不会覆盖 WordPress 自动添加的类(如wp-post-image、attachment-medium),而是追加。
二、”设置 → 媒体”页面详解
后台路径:设置 → 媒体(Settings → Media)
这个页面控制的是 WordPress 上传时自动生成的图片尺寸。
界面结构
各设置项说明
1. 缩略图大小(Thumbnail size)
- 宽度 × 高度:默认 150×150
- “裁剪缩略图到精确尺寸”复选框:
- 勾选:硬裁剪(crop),输出精确的 150×150,多余部分裁掉
- 不勾选:等比缩放(proportional),在 150×150 的”盒子”里缩放,实际可能是 150×100
这是唯一一个在后台有”硬裁剪”开关的尺寸。
2. 中等大小(Medium size)
- 最大宽度 × 最大高度:默认 300×300
- 没有裁剪选项,永远是等比缩放
- 原图 900×300 → 生成 300×100(宽缩到 300,高等比)
- 原图 600×600 → 生成 300×300(刚好等比)
3. 大尺寸(Large size)
- 最大宽度 × 最大高度:默认 1024×1024
- 同样没有裁剪选项,永远是等比缩放
4. 上传文件
- “按年月组织上传文件夹”:勾选后,上传的图片会按
wp-content/uploads/2026/11/ 这样的目录结构存放
三、核心问题:为什么”最大 300×300″不等于”精确 300×300″?
1. 缩略图大小(Thumbnail size)
- 宽度 × 高度:默认 150×150
- “裁剪缩略图到精确尺寸”复选框:
- 勾选:硬裁剪(crop),输出精确的 150×150,多余部分裁掉
- 不勾选:等比缩放(proportional),在 150×150 的”盒子”里缩放,实际可能是 150×100
这是唯一一个在后台有”硬裁剪”开关的尺寸。
2. 中等大小(Medium size)
- 最大宽度 × 最大高度:默认 300×300
- 没有裁剪选项,永远是等比缩放
- 原图 900×300 → 生成 300×100(宽缩到 300,高等比)
- 原图 600×600 → 生成 300×300(刚好等比)
3. 大尺寸(Large size)
- 最大宽度 × 最大高度:默认 1024×1024
- 同样没有裁剪选项,永远是等比缩放
4. 上传文件
- “按年月组织上传文件夹”:勾选后,上传的图片会按
wp-content/uploads/2026/11/ 这样的目录结构存放
三、核心问题:为什么”最大 300×300″不等于”精确 300×300″?
- 勾选:硬裁剪(crop),输出精确的 150×150,多余部分裁掉
- 不勾选:等比缩放(proportional),在 150×150 的”盒子”里缩放,实际可能是 150×100
这是唯一一个在后台有”硬裁剪”开关的尺寸。
- 最大宽度 × 最大高度:默认 300×300
- 没有裁剪选项,永远是等比缩放
- 原图 900×300 → 生成 300×100(宽缩到 300,高等比)
- 原图 600×600 → 生成 300×300(刚好等比)
3. 大尺寸(Large size)
- 最大宽度 × 最大高度:默认 1024×1024
- 同样没有裁剪选项,永远是等比缩放
4. 上传文件
- “按年月组织上传文件夹”:勾选后,上传的图片会按
wp-content/uploads/2026/11/ 这样的目录结构存放
三、核心问题:为什么”最大 300×300″不等于”精确 300×300″?
- “按年月组织上传文件夹”:勾选后,上传的图片会按
wp-content/uploads/2026/11/这样的目录结构存放
三、核心问题:为什么”最大 300×300″不等于”精确 300×300″?
这是最容易混淆的地方。
“最大尺寸”(Max Width / Max Height)的含义
WordPress 后台的”中等大小 300×300″和”大尺寸 1024×1024″,这里的数字是上限,不是目标尺寸。
规则是:
图片会被等比缩小,直到宽度和高度都不超过设定的最大值。
举例:
| 原图尺寸 | medium(最大 300×300)实际生成 | large(最大 1024×1024)实际生成 |
|---|---|---|
| 1920×1080 | 300×169 | 1024×576 |
| 900×300 | 300×100 | 900×300(未超 1024,不缩) |
| 600×600 | 300×300 | 600×600(未超 1024,不缩) |
| 200×150 | 200×150(比 300 小,不缩) | 200×150 |
所以:
- 你看到”媒体库里有 300×300 的图”,是因为那张原图恰好比例接近 1:1
- 你那张 300×100 多的图,是因为原图比例不是 1:1,
medium只把宽缩到 300,高度按比例跟着缩
只有 thumbnail 有”硬裁剪”选项
在后台”设置 → 媒体”中,**只有缩略图(thumbnail)**有”裁剪到精确尺寸”的复选框。medium 和 large 永远是等比缩放,没有硬裁剪选项。
四、如何获得”精确尺寸”的图片?
方法一:add_image_size() 注册硬裁剪尺寸(推荐)
// functions.php
add_action('after_setup_theme', function () {
// 参数:名称, 宽, 高, 是否硬裁剪
add_image_size('card-300', 300, 300, true); // 精确 300×300
add_image_size('card-600', 600, 600, true); // 精确 600×600(Retina)
});
// functions.php
add_action('after_setup_theme', function () {
// 参数:名称, 宽, 高, 是否硬裁剪
add_image_size('card-300', 300, 300, true); // 精确 300×300
add_image_size('card-600', 600, 600, true); // 精确 600×600(Retina)
});
调用:
the_post_thumbnail('card-300');
️ 注册新尺寸后,只有新上传的图片才会自动生成。已有图片需要安装 Regenerate Thumbnails 插件重新生成。
方法二:set_post_thumbnail_size() 修改默认尺寸
// functions.php
set_post_thumbnail_size( 300, 300, true ); // 精确 300×300,硬裁剪
// functions.php
set_post_thumbnail_size( 300, 300, true ); // 精确 300×300,硬裁剪
这会影响 the_post_thumbnail() 不传参数时的默认输出。
方法三:后台勾选”裁剪缩略图到精确尺寸”
在”设置 → 媒体”中勾选该选项,thumbnail 就会变成硬裁剪。但这只影响 thumbnail 尺寸,不影响 medium 和 large。
五、array(300, 300) 的实际行为
回到你觉得”很合适”的写法:
the_post_thumbnail( array(300, 300) );
它的实际工作流程:
- WordPress 查找该附件所有已生成的尺寸文件
- 从中选出最接近 300×300 的那个
- 输出对应的
<img>标签
它不会:
- 现场裁剪生成新图
- 放大小图
- 保证输出精确 300×300
它只是:
- 从已有尺寸里”挑一个最合适的”
所以如果你的原图是 900×300,array(300, 300) 很可能返回的就是 medium 尺寸的 300×100,因为那是最接近的已有尺寸。
六、最佳实践总结
| 需求 | 做法 |
|---|---|
| 需要精确 300×300 | add_image_size('card', 300, 300, true) + the_post_thumbnail('card') |
| 需要 Retina 高清 | 注册 2 倍尺寸(如 600×600),CSS 写 300px 宽 |
| 只想从已有尺寸中选 | the_post_thumbnail(array(300, 300)) |
| 已有图片没生成新尺寸 | 安装 Regenerate Thumbnails 插件重新生成 |
| 只要 URL 不要 img 标签 | wp_get_attachment_image_src($id, 'card-300') |
| 限制上传最小尺寸 | wp_handle_upload_prefilter 过滤器拦截 |
七、常用相关函数速查
// 检查是否有特色图
has_post_thumbnail();
// 获取特色图 ID
get_post_thumbnail_id();
// 获取特色图 HTML(不直接输出)
get_the_post_thumbnail( $post_id, $size, $attr );
// 获取特色图 URL、宽、高
$image = wp_get_attachment_image_src( get_post_thumbnail_id(), 'card-300' );
$url = $image[0];
$width = $image[1];
$height = $image[2];
// 注册新尺寸
add_image_size( 'name', $width, $height, $crop );
// 设置默认 post-thumbnail 尺寸
set_post_thumbnail_size( $width, $height, $crop );
一句话总结:后台”设置 → 媒体”里的 medium 和 large 是最大上限(等比缩放),只有 thumbnail 有硬裁剪选项;想要精确尺寸,用 add_image_size() 注册硬裁剪尺寸是最可靠的方式;array(300, 300) 只是从已有尺寸中”挑最接近的”,不保证精确。
