WooCommerce自定义免费配送方法配置无法保存问题排查
WooCommerce自定义免费配送方法配置无法保存的修复方案
问题根因定位
现有代码存在3个直接阻断配置持久化的问题:
- 设置更新钩子绑定错误:原代码给全局方法ID绑定了
woocommerce_update_options_shipping_{$this->id}钩子,但因为方法声明了支持配送区域实例(shipping-zones、instance-settings特性),WooCommerce 2.6+版本后这类方法的配置是按配送区域实例维度存储的,全局钩子根本不会触发,导致保存动作没有对应处理逻辑。 - 类加载判断不匹配:原代码判断类是否存在时用的类名
Imp_WC_Shipping_Free_Local_Pickup,和实际定义的类名Imp_WC_Pickup_Free_Shipping_Method不一致,会导致类加载校验失效,绕过父类的初始化流程。 - 配送费率参数非法:原代码在
calculate_shipping方法里给cost和calc_tax传了空字符串,WooCommerce的校验逻辑会直接拦截这类非法参数的费率提交,连带把配置保存的请求标记为无效,不执行存储流程。
修复后功能说明
可以完全实现和WooCommerce默认免费配送方法的字段、判断逻辑完全一致,同时保留独立唯一的方法ID,和系统自带方法互不干扰:
- 所有配置字段对齐系统默认免费配送:可自定义前端显示标题、设置免费配送触发规则(无限制/需优惠券/满最低金额/满足任一条件/同时满足两个条件)
- 配置完全持久化:每个配送区域下的方法实例配置会独立存储,保存后刷新不会丢失
- 结算页判断逻辑和系统方法完全一致:会根据购物车金额、用户使用的优惠券自动判断是否展示免费配送选项

可直接使用的修复代码
if ( ! defined( 'WPINC' ) ) { die; } // 校验WooCommerce是否处于激活状态 if ( in_array( 'woocommerce/woocommerce.php', apply_filters( 'active_plugins', get_option( 'active_plugins' ) ) ) ) { function enviogratuitopeninsula_shipping_init() { // 修正类存在判断逻辑,和实际定义的类名完全匹配 if ( ! class_exists( 'Imp_WC_Pickup_Free_Shipping_Method' ) ) { class Imp_WC_Pickup_Free_Shipping_Method extends WC_Shipping_Method { /** * 构造函数 * @param int $instance_id */ public function __construct( $instance_id = 0 ) { $this->id = 'imp_enviopeninsulagratuito_method'; $this->instance_id = absint( $instance_id ); $this->method_title = __( "半岛地区免费配送", 'imp' ); $this->method_description = __( "独立自定义的免费配送方法,逻辑与WooCommerce默认免费配送完全对齐", 'imp' ); $this->supports = array( 'shipping-zones', 'instance-settings', 'instance-settings-modal', ); $this->init(); } /** * 初始化配送方法 */ public function init() { // 加载实例设置的表单字段 $this->init_instance_form_fields(); // 加载当前配送区域下的实例配置 $this->init_instance_settings(); // 读取已存储的实例配置值 $this->title = $this->get_instance_option( 'title' ); $this->requires = $this->get_instance_option( 'requires' ); $this->min_amount = $this->get_instance_option( 'min_amount' ); // 绑定正确的实例设置更新钩子 add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_instance_settings' ) ); } /** * 定义实例设置表单字段,完全对齐WooCommerce默认免费配送的字段结构 */ public function init_instance_form_fields() { $this->instance_form_fields = array( 'title' => array( 'title' => __( '显示标题', 'woocommerce' ), 'type' => 'text', 'description' => __( '用户在结算页看到的配送选项标题', 'woocommerce' ), 'default' => __( '免费配送', 'woocommerce' ), 'desc_tip' => true, ), 'requires' => array( 'title' => __( '免费配送触发规则', 'woocommerce' ), 'type' => 'select', 'class' => 'wc-enhanced-select', 'default' => '', 'options' => array( '' => __( '无限制', 'woocommerce' ), 'coupon' => __( '需要有效免费配送优惠券', 'woocommerce' ), 'min_amount' => __( '满足最低订单金额', 'woocommerce' ), 'either' => __( '满足最低订单金额 或 有效优惠券', 'woocommerce' ), 'both' => __( '同时满足最低订单金额 和 有效优惠券', 'woocommerce' ), ), ), 'min_amount' => array( 'title' => __( '最低订单金额', 'woocommerce' ), 'type' => 'price', 'placeholder' => wc_format_localized_price( 0 ), 'description' => __( '达到该金额即可享受免费配送(仅在对应规则启用时生效)', 'woocommerce' ), 'default' => '0', 'desc_tip' => true, ), ); } /** * 计算配送费用:逻辑完全对齐WooCommerce默认免费配送 * @param array $packages */ public function calculate_shipping( $packages = array() ) { $show_free_shipping = true; // 按配置规则校验是否满足免费配送条件 switch ( $this->requires ) { case 'coupon': if ( ! $this->has_valid_free_shipping_coupon() ) { $show_free_shipping = false; } break; case 'min_amount': if ( WC()->cart->get_displayed_subtotal() < $this->min_amount ) { $show_free_shipping = false; } break; case 'either': $coupon_valid = $this->has_valid_free_shipping_coupon(); $amount_valid = WC()->cart->get_displayed_subtotal() >= $this->min_amount; if ( ! $coupon_valid && ! $amount_valid ) { $show_free_shipping = false; } break; case 'both': $coupon_valid = $this->has_valid_free_shipping_coupon(); $amount_valid = WC()->cart->get_displayed_subtotal() >= $this->min_amount; if ( ! $coupon_valid || ! $amount_valid ) { $show_free_shipping = false; } break; } // 校验通过则注册合法的免费配送费率(修正之前空参数的错误) if ( $show_free_shipping ) { $rate = array( 'id' => $this->get_rate_id(), 'label' => $this->title, 'cost' => 0, 'calc_tax' => 'per_order', ); $this->add_rate( $rate ); } } /** * 校验购物车中是否存在有效免费配送优惠券 * @return bool */ private function has_valid_free_shipping_coupon() { $applied_coupons = WC()->session->get( 'applied_coupons', array() ); if ( empty( $applied_coupons ) ) { return false; } foreach ( $applied_coupons as $coupon_code ) { $coupon = new WC_Coupon( $coupon_code ); if ( $coupon->get_free_shipping() ) { return true; } } return false; } } } } add_action( 'woocommerce_shipping_init', 'enviogratuitopeninsula_shipping_init' ); // 将自定义方法注册到WooCommerce全局配送方法列表 function register_imp_free_shipping_method( $methods ) { $methods['imp_enviopeninsulagratuito_method'] = 'Imp_WC_Pickup_Free_Shipping_Method'; return $methods; } add_filter( 'woocommerce_shipping_methods', 'register_imp_free_shipping_method' ); }
注意事项
- 替换代码后需要在WooCommerce配送区域设置页重新添加一次该自定义方法,旧的无效实例配置不会自动迁移
- 方法ID全程独立为
imp_enviopeninsulagratuito_method,不会和WooCommerce自带的free_shipping方法产生任何冲突 - 所有配置存储在WordPress options表的实例专属键值下,不会被其他配送方法的配置覆盖
内容的提问来源于stack exchange,提问作者Manuel
相关产品推荐
相关产品推荐

