WordPress自定义裁剪缩略图不显示 调用仅返回原图问题

这个问题的本质是WordPress数据库中存储的附件元数据没有记录你注册的自定义图片尺寸信息，虽然物理裁剪文件已经生成到服务器目录，但WordPress读取图片地址时优先查询数据库元数据，查不到对应尺寸就会自动回退返回原图地址。
常见触发场景：

• 自定义图片尺寸注册时机错误，没有挂在正确的钩子上执行，WordPress初始化图片尺寸列表时没有拿到你注册的尺寸规则，后续生成/读取缩略图时就不会识别这个尺寸
• 使用重新生成缩略图的工具时，工具只生成了物理文件，没有同步更新附件对应的postmeta元数据记录
• 自定义尺寸名称和其他插件、主题注册的尺寸重名，被其他规则覆盖

• 第一步：修正自定义尺寸的注册逻辑
  所有add_image_size调用必须挂在after_setup_theme钩子下执行，不能直接写在functions.php全局作用域，也不能挂在init及更晚触发的钩子上，正确注册代码如下：

// 注册自定义图片尺寸
function custom_register_image_sizes() {
    add_image_size('about-us-slider-image', 610, 820, true);
}
add_action('after_setup_theme', 'custom_register_image_sizes');

• 第二步：补全已有附件的元数据
  你已经确认服务器上存在对应裁剪文件，不需要重复生成图片，只需要把尺寸信息写入数据库即可。可以临时在主题模板里加入下面的代码，刷新一次页面执行后删除即可：

// 替换为你实际的图片附件ID
$target_attach_id = $imgID;
$attach_meta = wp_get_attachment_metadata($target_attach_id);

if (!isset($attach_meta['sizes']['about-us-slider-image'])) {
    // 按WordPress默认命名规则拼接裁剪文件名
    $file_parts = pathinfo($attach_meta['file']);
    $crop_file_name = sprintf(
        '%s-610x820.%s',
        $file_parts['filename'],
        $file_parts['extension']
    );

    // 写入尺寸信息
    $attach_meta['sizes']['about-us-slider-image'] = [
        'file'      => $crop_file_name,
        'width'     => 610,
        'height'    => 820,
        'mime-type' => get_post_mime_type($target_attach_id)
    ];

    wp_update_attachment_metadata($target_attach_id, $attach_meta);
}

• 第三步：排查重名冲突
  搜索当前主题代码、已启用插件代码，确认没有其他地方使用about-us-slider-image作为尺寸名注册不同参数的图片规则。如果存在重名，给尺寸名加上唯一前缀（比如主题缩写）即可，例如themename_about_slider。

完成以上操作后，再调用wp_get_attachment_image_url($imgID, 'about-us-slider-image')就能正常获取到裁剪后的图片地址，不会再回退到原图。

内容的提问来源于stack exchange，提问作者Giorgi Khatchapuridze