WordPress 缩略图与特色图片：调用、裁剪与常见问题
缩略图相关的问题，九成集中在三件事上：尺寸没注册、老图没有重新生成、调用函数用错了。至于「换主题之后列表图全空了」，那不是图片丢了，是新主题注册的尺寸名和旧的不一样，数据库里那张图的所有派生文件都对不上号。
先把三个概念分开
很多人把「缩略图」和「特色图片」当成同一件事，实际上一个是文件，一个是关系。分不清这两个，排查时方向就会错。
| 概念 | 本质 | 存在哪里 | 谁决定 |
|---|---|---|---|
| 原图 | 上传的原始文件 | uploads/2026/11/photo.jpg |
上传者 |
| 缩略图尺寸 | 由原图裁出的派生文件 | 同目录，文件名带 -720x405 后缀 |
add_image_size 与「设置 → 媒体」 |
| 特色图片 | 文章与某个附件 ID 的绑定关系 | wp_postmeta 的 _thumbnail_id |
编辑在编辑器侧栏指定 |
| 文章内插图 | 正文里的 img 标签 |
wp_posts.post_content |
编辑插入时选用的尺寸 |
所以「特色图片」本身不是一张特定尺寸的图，它只是一条记录：这篇文章的代表图是附件 1234。真正输出到页面上是哪个尺寸，由模板里 the_post_thumbnail() 传的参数决定。同一张特色图片，在首页卡片上可以是 720×405，在文章页头图可以是 1200×675，靠的是同一张原图派生出的多份文件。
add_image_size 注册尺寸
自定义尺寸必须在主题的 functions.php 里注册，而且要挂在 after_setup_theme 上，挂早了 WordPress 还没准备好图像处理功能。
add_action( 'after_setup_theme', function () {
add_theme_support( 'post-thumbnails' );
add_image_size( 'card', 720, 405, true ); // 16:9 硬裁剪
add_image_size( 'card-2x', 1440, 810, true ); // 高分屏
add_image_size( 'card-top', 720, 405, array( 'center', 'top' ) ); // 从上方裁
} );第四个参数决定裁剪方式：true 是硬裁剪，先把图缩放到刚好覆盖目标尺寸，再裁掉多余部分，保证输出尺寸精确；false 是等比缩放，长边贴合，另一边按比例算，输出尺寸不固定。列表页用固定比例的卡片，必须用 true，否则几张图高度不一会把网格撑乱。
注册尺寸要克制。每加一个尺寸，之后每张上传的图都会多生成一份文件，20 个尺寸乘以 5000 张图就是十万个文件，备份、rsync、CDN 回源都会被拖慢。常见做法是「一个展示尺寸 + 一个 2 倍图」就够，最多再加一个竖版用于移动端。
注册只对之后上传的图生效，这是最容易踩的坑。改完尺寸名，老文章仍然指向旧尺寸，模板会退回原图或者干脆输出空。必须重新生成，见后文。
the_post_thumbnail 怎么调
模板里不要直接读 _thumbnail_id 拼 URL，用官方函数，它会自动处理 srcset、宽高属性和懒加载。
<?php if ( has_post_thumbnail() ) : ?>
<?php the_post_thumbnail( 'card', array(
'alt' => get_the_title(),
'loading' => 'lazy',
'class' => 'card-img',
) ); ?>
<?php else : ?>
<img src="/static/placeholder.jpg" alt="" width="720" height="405">
<?php endif; ?>三个细节值得注意。第一，一定要有 has_post_thumbnail() 判断，否则没设特色图片的文章会输出一个空标签，在网格里留一块空白。第二，alt 建议用文章标题，比留空对 SEO 友好，也比自动读取附件标题可控。第三，首屏第一张图不要加 loading="lazy"，会拖慢 LCP，只在列表页第二张之后加。
如果只需要 URL 做 CSS 背景图，用 get_the_post_thumbnail_url( get_the_ID(), 'card' )；需要自己拼 picture 标签时用 get_the_post_thumbnail 拿到字符串再处理。这几个函数都支持传尺寸名，传一个没注册的名字不会报错，会静默退回原图——这也是很多人以为「尺寸设置生效了」其实是输出原图的原因。
裁剪位置：人脸上半部分被切掉怎么办
默认裁剪是从中心开始，人物照经常会切掉额头或者下巴。第三个参数写成数组就能指定锚点，array( 'center', 'top' ) 表示水平居中、垂直靠上，适合人像；产品图通常用 array( 'center', 'center' )，也就是默认值。
要注意后台媒体库「编辑图片」里的裁剪是另一回事：它直接改原图，然后重新生成所有尺寸，只适合修一张构图有问题的图，不能用来批量调整某个尺寸的取景。想按尺寸控制，只能在代码里改 crop 参数，再重新生成。
如果同一批图有的是横构图有的是竖构图，硬裁剪到 16:9 必然有损失。这种情况建议注册两个尺寸（横版卡片、竖版卡片），在模板里按原图比例判断用哪个，而不是用一个尺寸强行裁。
列表缩略图自适应
「图片被拉变形」几乎都是 CSS 的问题，不是 WordPress 的问题。the_post_thumbnail 输出的 img 带 width 和 height 属性，如果容器宽度变化而 height 被固定，图就扁了。正确的写法是让图片填满容器、按比例裁切：
.card-media { aspect-ratio: 16 / 9; overflow: hidden; }
.card-media img { width: 100%; height: 100%; object-fit: cover; display: block; }aspect-ratio 让容器在任何宽度下都保持 16:9，object-fit: cover 让图片裁剪填充而不是拉伸。这套写法不依赖图片本身的尺寸，即使某篇文章的特色图片是 4:3，卡片也不会变形。
另外，the_post_thumbnail 默认会输出 srcset，浏览器按容器宽度和 DPR 选图。前提是你注册的尺寸覆盖了这些宽度；只注册一个 720px 的话，在 1440px 宽的屏幕上只能拉到原图，等于没做响应式，首屏图也会明显拖慢 加载速度。这就是「一个展示尺寸 + 一个 2 倍图」的实际意义。
换主题后缩略图不显示：按顺序查
改版或者换主题之后列表图消失，按下面的顺序查，比乱试快。
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 整站所有列表图都是空白 | 新主题没写 add_theme_support( 'post-thumbnails' ) |
在 after_setup_theme 里补上 |
| 图有空位但加载不出来 | 模板里用了旧主题注册的尺寸名 | 改用新尺寸名，或补注册旧名字 |
| 只有老文章没图，新发的正常 | 尺寸是新注册的，老图没生成派生文件 | 批量重新生成缩略图 |
| 图有了但是糊的 | 调用了 thumbnail（默认 150×150） |
改成自定义尺寸名 |
| 后台能看到特色图片，前台没有 | 模板没调用，或调用在循环外 | 检查 the_post_thumbnail 是否在 have_posts() 循环内 |
重新生成可以用 wp media regenerate --only-missing，只补缺的，不动已有的；也可以装 Regenerate Thumbnails 插件在后台点。图片上万时命令行更稳，避免请求超时，跑之前先确认 memory_limit 和 max_execution_time 够用。网站改版 时建议在测试环境先跑一遍，确认新尺寸的裁剪效果符合设计稿再上生产。如果 uploads 里的文件本身在搬家过程中丢了，缩略图再生成也补不回来，这时候要按 迁移搬家 的检查项先核对目录完整性。
外链特色图片的取舍
有些站为了省磁盘，把特色图片字段存成外链 URL，模板里直接输出第三方地址。这个做法在演示站上没问题，做正式站要谨慎。
- 好处：不占本地磁盘，图片本身走对方 CDN，源站带宽压力小。
- 坏处：WordPress 拿不到图片尺寸，无法生成多尺寸，也就没有
srcset，移动端会加载原图。 - 坏处：
og:image、sitemap 的图片节点、结构化数据都可能拿不到这张图，社交分享时没有缩略图。 - 坏处：对方改路径、加防盗链、或者站点关停，你的列表页就是一片空白，而且没有任何本地备份。
折中方案是把外链图下载到媒体库再设为特色图片，后台「媒体 → 添加新媒体 → 从 URL 上传」就能做，成本只有一次点击，换来的是完整的尺寸体系和可备份性。真要长期用远程图，至少在本站留一份缩略图副本，并且给 img 加 onerror 之外的兜底样式——纯 CSS 兜底比内联脚本更安全。
一次性把尺寸体系理顺
- 列出模板里实际用到的所有图片位置和尺寸，包括卡片、横幅、侧栏、相关推荐。
- 合并相近尺寸，控制在 3 至 4 个以内，每个都给一个语义化的名字，别用
thumb1、thumb2。 - 在
functions.php里统一注册，写清注释说明用在哪个模板。 - 跑一次
wp media regenerate，然后抽查三种比例的图（横、竖、方）。 - 把「设置 → 媒体」里的三个默认尺寸也调成实际会用到的值，避免生成永远用不上的 150×150 和 768 宽。
尺寸体系一旦乱掉，后面每次改版都要重来一遍，所以值得在建站阶段就定下来。信科网络在做 主题定制 时会把这些尺寸和模板位置一起写进交付文档，后面换设计也不用猜。有需要可以打 13280692153。