本文介绍如何在 woocommerce 商品列表页（如分类归档页）中，优先显示产品所属第一个分类的描述文字；当描述为空时，回退显示该分类的名称，并避免多分类导致的重复输出问题。
在 WooCommerce 默认的商品分类归档页（如 /product-category/books/）中，页面顶部通常会显示当前分类的名称与描述（通过 woocommerce_archive_description 钩子输出）。但若需自定义逻辑——例如：仅当分类描述非空时显示描述，否则显示名称，且确保每个商品只取其首个有效分类信息（而非合并所有分类字段），则需谨慎处理 get_the_terms() 返回的数组结构。
原始代码的问题根源在于：
- get_the_terms($product->get_id(), 'product_cat') 返回的是当前产品所属的所有分类对象数组（可能含多个分类）；
- wp_list_pluck($cats, 'description') 生成的是包含所有分类描述的数组，join('', ...) 会将它们拼接成一个长字符串；
- 若产品同时属于“图书”和“畅销品”两个分类，且仅“图书”有描述，则拼接结果仍为该描述；但若两者均无描述，join('', ['','']) 得到空字符串，后续 $categ 拼接后却输出 "图书畅销品"——造成视觉上的“名称重复”或冗余。
而修正后的方案关键在于：只取第一个分类（通常是主分类）的数据，而非聚合全部：
function cat_description() {
global $product;
// 获取当前产品所属的所有 product_cat 分类对象
$cats = get_the_terms( $product->get_id(), 'product_cat' );
// 安全检查：确保 $cats 有效且非空
if ( ! $cats || is_wp_error( $cats ) ) {
return;
}
// 提取第一个分类的描述和名称（索引 0）
$cat_descr = wp_list_pluck( $cats, 'description' );
$cat_name = wp_list_pluck( $cats, 'name' );
echo '<div class="mf-catalog-title">';
if ( ! empty( $cat_descr[0] ) ) {
echo esc_html( $cat_descr[0] );
} else {
echo esc_html( $cat_name[0] );
}
echo '</div>';
}
add_action( 'woocommerce_archive_description', 'cat_description', 2 );✅ 优势说明：
- 使用 $cat_descr[0] 明确限定使用首个分类的描述，彻底规避多分类拼接问题；
- 增加 is_wp_error() 和空值判断，提升健壮性；
- 使用 esc_html() 对输出内容进行转义，防止 XSS 风险；
- 保留原有钩子优先级 2，确保在主题默认输出前执行（便于 CSS 隐藏原生标题）。
⚠️ 关于隐藏主题默认分类标题：
若主题自行调用了 woocommerce_category_image() 或直接 echo $category->name，可通过移除默认动作实现干净覆盖。常见方式是定位主题或 WooCommerce 核心中输出位置，例如：
// 移除 WooCommerce 默认的分类名称+描述输出（如果存在冗余） remove_action( 'woocommerce_archive_description', 'woocommerce_taxonomy_archive_description', 10 );
将其加入 functions.php，可确保你的 cat_description() 成为唯一输出源。
? 总结：多分类场景下，应避免对 wp_list_pluck 结果直接 join()，而应基于业务逻辑选取特定索引项。本方案兼顾准确性、安全性与可维护性，适用于标准 WooCommerce 主题及多数子主题环境。
