lumen-mimangfei 主题特色图片与缩略图尺寸设置：推荐尺寸与裁剪规则

引言：图传上去了，却被裁得七零八落

最典型的情况：换了主题之后，列表里的缩略图有的被裁成正方形、有的留出大片空白，商品图被拉伸变形；或者明明设置了特色图片，前台就是不显示；再或者上传一张 4000px 的大图，媒体库里只剩一张被压到 2560px 的版本，原图找不到了。

这些都不是”主题坏了”，而是缩略图尺寸注册、裁剪方式、响应式属性三件事没对上。lumen-mimangfei 主题会注册自己的图片尺寸，换主题后旧图不会自动重生成新尺寸的裁剪文件，于是只能用最接近的旧尺寸顶替，比例自然对不上。

原理分析：尺寸注册、裁剪与 srcset

主题用 add_theme_support( 'post-thumbnails' ) 开启特色图片，用 set_post_thumbnail_size() 设默认尺寸，用 add_image_size( $name, $w, $h, $crop ) 注册额外尺寸。第四个参数 $crop 决定裁剪行为：false（软裁剪，等比缩放不裁切）、true（硬裁剪，从中心裁到指定尺寸）、数组（如 array( 'left', 'top' )）指定裁切锚点。

关键点：尺寸只在图片上传那一刻生成。 换主题、改尺寸之后，历史图片不会自动补出新尺寸，需要重建缩略图（Regenerate Thumbnails 插件或 wp media regenerate）。

前台 the_post_thumbnail( 'size' ) 会输出带 srcset 与 sizes 的 <img>，浏览器按屏幕宽度挑选合适文件。若某个尺寸缺失，它会退化到已有尺寸。另外 WordPress 从 5.3 起对超大图做缩放：宽度或高度超过阈值的上传图会被生成 -scaled 版本并作为原图使用，阈值由 big_image_size_threshold 过滤器控制，默认 2560。

保姆级实操

1. 先确认主题需要哪些尺寸：搜索主题里的 add_image_size 与 the_post_thumbnail，记录尺寸名与宽高。
2. 确定推荐上传尺寸：列表缩略图建议按 3:2 或 4:3 统一比例上传，宽度不低于 1200px，既能覆盖列表又能覆盖正文大图。
3. 注册自定义尺寸：在子主题 after_setup_theme 里补尺寸，并把它加进后台下拉，方便编辑器选择。
4. 把尺寸加进 srcset 候选：自定义尺寸默认不会全部进入 srcset，需要用 wp_calculate_image_srcset 或注册时保持与已有比例一致。
5. 重建历史缩略图：用 WP-CLI 批量重生成，大站建议分批执行避免超时。
6. 调整超大图阈值：摄影类站点如果确实需要原图，可以提高阈值或关闭缩放。
7. 核对前台输出：查看图片元素的 srcset，确认候选尺寸存在。

<?php
// 子主题 functions.php：注册列表卡片与详情页大图两种尺寸
add_action( 'after_setup_theme', 'mimangfei_image_sizes' );
function mimangfei_image_sizes() {
    add_theme_support( 'post-thumbnails' );
    set_post_thumbnail_size( 800, 600, true );

    // 列表卡片：4:3 硬裁剪，锚点居中偏上，避免人物头部被切
    add_image_size( 'mimangfei-card', 600, 450, array( 'center', 'top' ) );
    // 详情页大图：等比缩放，不裁切
    add_image_size( 'mimangfei-wide', 1200, 0, false );
    // 移动端列表小图：2:1
    add_image_size( 'mimangfei-thin', 640, 320, true );
}

// 让自定义尺寸出现在后台与区块编辑器的尺寸下拉里
add_filter( 'image_size_names_choose', 'mimangfei_size_names' );
function mimangfei_size_names( $sizes ) {
    return array_merge( $sizes, array(
        'mimangfei-card' => __( '列表卡片 4:3', 'lumen-mimangfei' ),
        'mimangfei-wide' => __( '详情大图', 'lumen-mimangfei' ),
    ) );
}

// 摄影站需要保留原图时，抬高超大图阈值
add_filter( 'big_image_size_threshold', function () {
    return 3840;
} );

<?php
// 只给首页列表输出卡片尺寸，其余位置用主题默认
if ( is_home() || is_archive() ) {
    the_post_thumbnail( 'mimangfei-card', array(
        'class'   => 'card-thumb',
        'loading' => 'lazy',
        'alt'     => esc_attr( get_the_title() ),
    ) );
} else {
    the_post_thumbnail( 'mimangfei-wide' );
}

# 重建全部历史图片的缩略图（大站建议加 --only-missing 或分批）
wp media regenerate --yes
# 只生成缺失的尺寸，速度更快
wp media regenerate --only-missing --yes
# 重建指定附件
wp media regenerate 123 456 --yes

# 查看某篇文章的特色图片 ID
wp post meta get 123 _thumbnail_id

常见踩坑

• 注册了新尺寸但没重建缩略图，历史图片仍然用最接近的旧尺寸，比例错乱。
• 上传前没统一比例，硬裁剪后主体被切掉。
• 自定义尺寸没加进 image_size_names_choose，后台选不到，误以为没注册成功。
• 用了 full 输出列表图，页面体积暴增，移动端加载缓慢。
• 案例：某摄影站换主题后，列表缩略图全部变成竖条。原因是新主题注册的是 4:3 硬裁剪，而历史图片只有旧主题的 1:1 与 16:9 版本，the_post_thumbnail() 退化到 16:9 后又被 CSS 的 height: 100% 拉伸。用 --only-missing 重生成一遍 4:3 尺寸后即恢复。
• 上传超过 2560px 的图被自动缩放，误以为”原图丢了”，其实是 -scaled 机制。
• 重建缩略图时没限制批次，PHP 超时中断，部分图片只生成了一半尺寸。

总结

核心规律：尺寸在上传时生成，换主题必须重建；$crop 决定比例是否统一；srcset 决定浏览器挑哪张。行动清单：① 统一上传比例与最小宽度；② 用 add_image_size 注册并用 image_size_names_choose 暴露；③ 换主题后立刻重建缩略图；④ 列表绝不用 full；⑤ 需要原图时调整 big_image_size_threshold。延伸阅读 lumen-mimangfei 主题性能优化、lumen-mimangfei 主题文章列表样式 与 WordPress 图片懒加载。