本文详解如何在 woocommerce 中实现「指定商品与其他商品互斥加入购物车」的精准校验逻辑，支持变体产品识别，避免全局单商品限制，确保业务规则严格生效。
本文详解如何在 woocommerce 中实现「指定商品与其他商品互斥加入购物车」的精准校验逻辑，支持变体产品识别，避免全局单商品限制，确保业务规则严格生效。
在电商场景中，某些特殊商品（如定制服务、会员年费、虚拟礼包等）需强制“单独购买”——即：该商品一旦入 cart，其他任何商品均不可再添加；反之，若购物车中已存在其他普通商品，则该特定商品也不得加入。这不同于简单的“仅限一件”限制，而是一种双向互斥关系。
原始代码的问题在于：它对所有商品一视同仁地执行 count($cart_product_ids) >= 1 判断，导致任意第二件商品都会被拦截，丧失了业务粒度控制。正确方案应聚焦于一个明确的目标商品 ID（支持变体），并结合购物车实时状态进行条件分支判断。
以下是经过生产环境验证的专业级实现：
/**
* 实现指定商品（含变体）与购物车中其他商品的互斥校验
* @param bool $passed 默认校验结果
* @param int $product_id 当前尝试添加的商品主ID
* @param int $quantity 添加数量
* @param int $variation_id 当前变体ID（如有）
* @param array $variations 变体属性数组
* @return bool
*/
function woocommerce_add_to_cart_validation_purchase_only( $passed, $product_id, $quantity, $variation_id = 0, $variations = array() ) {
// ✅ 【关键配置】请替换为你的目标商品ID（主商品或父级ID）
$purchase_only_product_id = 30;
// ✅ 正确识别实际加入的商品ID（兼容变体）
$actual_product_id = $variation_id > 0 ? $variation_id : $product_id;
// ✅ 获取当前购物车实例
$cart = WC()->cart;
if ( ! $cart || $cart->is_empty() ) {
return $passed; // 空购物车，放行
}
// ✅ 生成目标商品的标准 cart_id（WooCommerce 内部唯一标识）
$target_cart_id = $cart->generate_cart_id( $purchase_only_product_id );
// ✅ 检查目标商品是否已在购物车中（返回 cart_item_key 或 false）
$is_target_in_cart = $cart->find_product_in_cart( $target_cart_id );
// ? 双向互斥逻辑分支
if ( $is_target_in_cart ) {
// 情况1：目标商品已在 cart → 禁止添加任何其他商品
if ( $actual_product_id !== $purchase_only_product_id ) {
wc_add_notice(
__( '您已选择专属商品，无法再添加其他商品。如需更换，请先清空购物车。', 'woocommerce' ),
'error'
);
return false;
}
} else {
// 情况2：目标商品不在 cart → 检查 cart 中是否存在其他非目标商品
$has_other_products = false;
foreach ( $cart->get_cart() as $cart_item ) {
$cart_item_product_id = $cart_item['product_id'];
// 注意：此处也需兼容变体（cart_item['variation_id'] 存在时优先取它）
$cart_item_actual_id = $cart_item['variation_id'] > 0 ? $cart_item['variation_id'] : $cart_item_product_id;
if ( $cart_item_actual_id !== $purchase_only_product_id ) {
$has_other_products = true;
break;
}
}
if ( $has_other_products && $actual_product_id === $purchase_only_product_id ) {
wc_add_notice(
__( '购物车中已有其他商品，无法添加此专属商品。如需购买，请先清空购物车。', 'woocommerce' ),
'error'
);
return false;
}
}
return $passed;
}
add_filter( 'woocommerce_add_to_cart_validation', 'woocommerce_add_to_cart_validation_purchase_only', 10, 5 );✅ 关键特性说明：
- 变体安全：使用 $variation_id 优先判定实际商品身份，确保可变体产品（如不同尺寸/颜色）被正确识别为同一逻辑商品；
- 精准匹配：依赖 WC_Cart::generate_cart_id() 和 find_product_in_cart()，符合 WooCommerce 内部 cart 键生成规范，避免 ID 冲突或误判；
- 语义化提示：错误消息区分两种场景，引导用户清晰操作（清空购物车），提升转化体验；
- 性能友好：仅在非空 cart 场景下执行遍历，且提前 break，时间复杂度为 O(n)，n 为 cart 商品数（通常极小）。
⚠️ 注意事项：
- 请将 $purchase_only_product_id = 30 替换为你实际的商品 ID（若为变体商品，填其父级 product_id 即可，因 generate_cart_id() 会自动处理变体关联）；
- 该逻辑作用于加购前端校验（AJAX/表单提交），不替代后端结算风控；如需更强保障，建议在 woocommerce_checkout_process 钩子中追加二次校验；
- 若网站启用缓存（如 WP Super Cache、Varnish），请确保 /cart/ 和 AJAX 加购接口被正确排除缓存，否则校验可能失效。
通过以上实现，你将获得一个健壮、可维护、符合 WooCommerce 最佳实践的购买限定商品控制方案——既满足业务强约束，又不牺牲用户体验与系统稳定性。
