WooCommerce商店页ACF自定义关联产品短代码异常排查

搭建WooCommerce商城，需要在商店/商品分类目录页为每个商品展示自定义关联商品。

环境配置 #

• 使用Advanced Custom Fields Pro插件
• 创建了字段组，包含名为product_relations的RELATION类型字段
• 已在后台商品编辑页通过product_relations字段为每个商品选定多个自定义关联商品，编写了对应shortcode用于商店/分类页展示，但输出不符合预期。

当前故障表现 #

页面仅显示最新一个商品的关联商品内容，效果参考：

原有短代码实现 #

function yl_product_relations_shortcode() {
    global $product;

    $product_relations = get_field('product_relations');

    if ($product_relations) {

        $output .= '<ul class="uk-thumbnav uk-margin-bottom">';

        foreach ($product_relations as $product_relation) {
            $title  = get_the_title($product_relation);
            $image  = get_the_post_thumbnail_url($product_relation);
            $url    = get_the_permalink($product_relation);

            $output .= '<li><a href="' . $url . '" uk-tooltip="' . $title . '"><img src="' . $image . '" class="uk-border-rounded" width="40"></a></li>';
        }

        $output .= '</ul>';

    }

    return $output;

}

add_shortcode('yl_product_relations','yl_product_relations_shortcode');

补充说明 #

通过WordPress Customizer调用[yl_product_relations]短代码拉取数据。尝试在代码中添加如下逻辑指定商品ID获取字段值时站点报错：

$id = $product->get_id();
$product_relations = get_field('product_relations', $id);

报错原因推测为Customizer中调用短代码时，代码未处于WooCommerce商品循环（product loop）内部，无法正确获取全局$product对象。

故障由两个核心问题共同导致：

1. 全局$product对象未做合法性校验，非循环场景下直接调用$product->get_id()会触发空对象报错
2. 短代码中$output变量未提前初始化，直接使用.=拼接会产生PHP隐式警告，叠加Customizer的输出缓冲逻辑导致内容串流，前面的商品内容被吞，仅输出最后一个商品的关联内容

修复后完整代码 #

function yl_product_relations_shortcode() {
    // 提前初始化输出变量，避免拼接报错
    $output = '';

    // 多场景兼容获取当前商品ID：循环内、自定义器预览、单商品页兜底
    global $product;
    if (is_a($product, 'WC_Product')) {
        $product_id = $product->get_id();
    } elseif (get_queried_object_id() && get_post_type(get_queried_object_id()) === 'product') {
        $product_id = get_queried_object_id();
    } else {
        // 非商品上下文直接返回空，不输出冗余内容
        return $output;
    }

    // 显式指定商品ID获取ACF字段，避免自动读取全局文章ID导致的取值错误
    $product_relations = get_field('product_relations', $product_id);

    if (!empty($product_relations)) {
        $output .= '<ul class="uk-thumbnav uk-margin-bottom">';
        foreach ($product_relations as $product_relation_item) {
            // 兼容ACF关系字段返回ID/对象两种配置，避免后台设置调整后代码失效
            $relation_id = is_a($product_relation_item, 'WP_Post') ? $product_relation_item->ID : $product_relation_item;
            $title       = get_the_title($relation_id);
            $image       = get_the_post_thumbnail_url($relation_id, 'thumbnail');
            $url         = get_the_permalink($relation_id);

            // 转义输出内容，避免特殊字符破坏HTML结构
            $output .= sprintf(
                '<li><a href="%s" uk-tooltip="%s"><img src="%s" class="uk-border-rounded" width="40" alt="%s"></a></li>',
                esc_url($url),
                esc_attr($title),
                esc_url($image),
                esc_attr($title)
            );
        }
        $output .= '</ul>';
    }

    return $output;
}
add_shortcode('yl_product_relations', 'yl_product_relations_shortcode');

适配说明 #

• 如果通过WooCommerce官方钩子（比如woocommerce_after_shop_loop_item）挂载短代码到商品卡片，上述代码可直接使用
• 如果用页面构建器/Customizer模块插入短代码，需确保模块位于商品循环的单个商品卡片内部，否则无法正确获取当前遍历的商品ID
• 若Customizer预览仍存在初始化报错，可在获取全局$product前添加wc_setup_product_data($GLOBALS['post'])，手动初始化商品数据适配非标准循环场景

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