WordPress 特色图片尺寸详解:the_post_thumbnail() 参数与媒体设置
番茄投手
10小时前
13

一、the_post_thumbnail() 函数基础

函数签名

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 ) );

这就是你觉得”很合适”的写法。它的行为是:

  • 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 上传时自动生成的图片尺寸。

界面结构

需求 做法
需要精确 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 过滤器拦截

各设置项说明

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″?

这是最容易混淆的地方。

“最大尺寸”(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)
});

调用:

the_post_thumbnail('card-300');

️ 注册新尺寸后,只有新上传的图片才会自动生成。已有图片需要安装 Regenerate Thumbnails 插件重新生成。

方法二:set_post_thumbnail_size() 修改默认尺寸

// 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) );

它的实际工作流程:

  1. WordPress 查找该附件所有已生成的尺寸文件
  2. 从中选出最接近 300×300 的那个
  3. 输出对应的 <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) 只是从已有尺寸中”挑最接近的”,不保证精确。

收藏
打赏
Orion 企业主题
上一篇
没有了
下一篇

发表评论

注册不是必须的

番茄投手
161 文章
3 评论
4 喜欢
最新文章

WordPress 特色图片尺寸详解:the_post_thumbnail() 参数与媒体设置

一、the_post_thumbnail() 函数基础 函数签名 the_post_thumbnail( $size, $attr ); 这个函数必须在主循环(The Loop)内使用,用于输出当前文章的特色图片(Featured Image)的完整 <img> 标签。如果要获取任意文章的缩略图 HTML 而非直接输出,用 get_the_post_thumbnail( $id, $s […]

Orion 企业主题

主题简介 Orion 主题是一款 WordPress 企业主题,支持自适应、暗黑模式等功能,可快速构建高质量的企业网站。   主题特色 支持白天与暗黑模式 自适应设计,兼容多种主流浏览器 自定义主色调 LOGO扫光动画 自定义SMTP支持 内置SEO功能 文章支持点赞、分享和海报生成 丰富的小工具 侧边栏粘性滚动 简介的主题设置面板 主题设置可导入和备份 多级子菜单支持 使用最新的的 E […]

Mirage 主题 v3.12.0 发布

Mirage 主题 v3.12.0 发布 https://github.com/vthemecn/mirage/releases/tag/v3.12.0 https://gitee.com/vthemecn/mirage/releases/tag/v3.12.0 更新内容: feat 可设置用户将无法通过 wp-login.php 进行注册或重置密码 feat 评论层级根据系统设置,最多支持3级, […]

Mirage 主题 v3.11.0 发布

Mirage 主题 v3.11.0 发布 https://github.com/vthemecn/mirage/releases/tag/v3.11.0 https://gitee.com/vthemecn/mirage/releases/tag/v3.11.0 这个版本优化了多个地方,并且屏蔽了 /wp-json/batch/v1,防止了 2026年7月被披露了极其严重的 WordPress 高 […]
生成中...
扫描二维码
扫描二维码
确认购买

您确定要购买此资源吗?

微信扫码支付

请使用微信扫描二维码完成支付

订单号:

等待支付...