本文介绍如何在 woocommerce 商品目录页（shop loop）中，为每个商品自动显示其所属首个产品分类（product_cat）的自定义缩略图徽章，兼容响应式尺寸与占位图回退机制。

在 WooCommerce 中，默认的商品循环（woocommerce_before_shop_loop_item_title 钩子）不包含分类缩略图展示功能。若需在商品标题上方统一显示其所属首个产品分类的自定义徽章（如品牌图标、品类标识等），应避免遍历全部分类或依赖硬编码 slug（如 'sunglasses'），而应采用健壮、可扩展的方式实现。

以下是一段经过优化的专业级代码，推荐添加至当前子主题的 functions.php 文件中：

/**
 * 在商品列表页顶部显示首个产品分类的缩略图徽章
 * 支持 WooCommerce 原生图片尺寸、srcset 响应式适配及占位图回退
 */
add_action('woocommerce_before_shop_loop_item_title', 'display_product_category_thumbnail', 20);
function display_product_category_thumbnail()
{
    global $product;

    // 获取当前商品的所有 product_cat 分类，并取第一个（按层级顺序，通常为最具体分类）
    $terms = get_the_terms($product->get_id(), 'product_cat');
    if (empty($terms) || is_wp_error($terms)) {
        return;
    }
    $first_category = reset($terms); // 等价于 array_shift()，但不修改原数组

    // 获取分类缩略图 ID（WooCommerce 4.4+ 推荐使用 term 
meta 的 thumbnail_id 字段）
    $thumbnail_id = get_term_meta($first_category->term_id, 'thumbnail_id', true);

    // 定义图片尺寸（复用 WooCommerce 标准缩略图配置）
    $size = 'woocommerce_thumbnail'; // 对应 300×300 或自定义尺寸（见 WooCommerce → 设置 → 产品 → 显示）
    $dimensions = wc_get_image_size($size);

    // 构建图像 URL 及响应式属性
    if ($thumbnail_id && wp_get_attachment_image_src($thumbnail_id, $size)) {
        $image_data = wp_get_attachment_image_src($thumbnail_id, $size);
        $image = is_array($image_data) ? $image_data[0] : '';
        $srcset = function_exists('wp_get_attachment_image_srcset') 
            ? wp_get_attachment_image_srcset($thumbnail_id, $size) 
            : false;
        $sizes = function_exists('wp_get_attachment_image_sizes') 
            ? wp_get_attachment_image_sizes($thumbnail_id, $size) 
            : false;
    } else {
        // 回退至 WooCommerce 占位图
        $image = wc_placeholder_img_src();
        $srcset = $sizes = false;
    }

    // 渲染徽章容器与图像（建议使用 CSS 控制宽高，而非内联 style）
    if ($image) {
        echo '';
        echo '@@##@@name)) . '"'
             . ' class="category-badge-img">';
        echo '';
    }
}

✅ 关键改进说明：

• ✅ 语义化 & 安全性： 使用 esc_url() 和 esc_attr() 防止 XSS；aria-hidden="true" 表明该图仅为装饰用途，不向屏幕阅读器暴露冗余信息。
• ✅ 响应式支持： 自动集成 srcset 和 sizes 属性，适配 Retina 屏与不同视口宽度。
• ✅ 兼容性： 兼容 WooCommerce 3.0+（get_term_meta 替代已废弃的 get_woocommerce_term_meta）；支持自定义图片尺寸配置。
• ✅ 鲁棒性： 增加空值与错误判断（is_wp_error、empty），避免 PHP 警告；使用 $product->get_id() 替代全局 $post->ID，更符合 WooCommerce 最佳实践。
• ✅ 样式建议： 请通过 CSS 控制 .category-badge-wrapper 和 .category-badge-img 的尺寸与布局（例如 max-width: 60px; height: auto;），避免使用内联 width="35%" 等不可维护写法。

⚠️ 注意事项：

• 确保已在「产品 → 分类」中为各分类上传了「图像」（即设置“分类图像”，后台自动存为 thumbnail_id meta）。
• 若需显示多个分类徽章（非仅首个），需重构逻辑并注意 DOM 性能与 UI 冗余问题，建议结合 CSS Grid/Flex 控制多徽章排列。
• 此钩子作用于所有商品卡片（包括搜索、分类归档等），如需限定页面，请包裹 is_shop()、is_product_category() 等条件判断。

通过以上实现，您将获得一个轻量、稳定、符合现代 Web 标准的分类徽章系统，显著提升商品列表页的信息传达效率与视觉专业度。