You need to enable JavaScript to run this app. WooCommerce自定义免费配送方法配置无法保存问题排查
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.30 16:27:03