自定义WooCommerce支付网关不显示问题求助

我在WooCommerce中开发了一个自定义支付网关，确认配置无误，但结账页面始终不显示该支付选项（附截图）；已添加包含日志的JS文件，日志能正常输出，本地环境运行，参考大量视频教程仍无法解决，插件代码如下：

<?php
/*
Plugin Name: My Custom Payment Gateway
Description: A custom payment gateway for WooCommerce.
Version: 1.0
Author: Your Name
*/

// Ensure WooCommerce is active
if (in_array('woocommerce/woocommerce.php', apply_filters('active_plugins', get_option('active_plugins')))) {
    // Add custom payment gateway class
    add_action('plugins_loaded', 'my_custom_payment_gateway_init', 5);
    function my_custom_payment_gateway_init() {
        class WC_Gateway_Custom extends WC_Payment_Gateway {
            public function __construct() {
                $this->id = 'custom_gateway';
                $this->icon = ''; // URL to an icon if you want to add
                $this->has_fields = true;
                $this->method_title = __('Custom Gateway', 'woocommerce');
                $this->method_description = __('Description of custom payment gateway', 'woocommerce');

                // Load the settings
                $this->init_form_fields();
                $this->init_settings();

                $this->title = $this->get_option('title');
                $this->description = $this->get_option('description');

                // Save settings
                add_action('woocommerce_update_options_payment_gateways_' . $this->id, array($this, 'process_admin_options'));
            }

            // Admin options
            public function init_form_fields() {
                $this->form_fields = array(
                    'enabled' => array(
                        'title' => __('Enable/Disable', 'woocommerce'),
                        'type' => 'checkbox',
                        'label' => __('Enable Custom Payment Gateway', 'woocommerce'),
                        'default' => 'yes'
                    ),
                    'title' => array(
                        'title' => __('Title', 'woocommerce'),
                        'type' => 'text',
                        'description' => __('This controls the title which the user sees during checkout.', 'woocommerce'),
                        'default' => __('Custom Payment', 'woocommerce'),
                        'desc_tip' => true,
                    ),
                    'description' => array(
                        'title' => __('Description', 'woocommerce'),
                        'type' => 'textarea',
                        'description' => __('This controls the description which the user sees during checkout.', 'woocommerce'),
                        'default' => __('Pay using our custom payment gateway.', 'woocommerce')
                    )
                );
            }

            // Display custom fields on the checkout page
            public function payment_fields() {
                // Description of the payment method
                if ($this->description) {
                    echo wpautop(wp_kses_post($this->description));
                }
                // Add custom fields here
                ?>
                <fieldset>
                    <p class="form-row form-row-wide">
                        <label for="<?php echo esc_attr($this->id); ?>-custom-field"><?php esc_html_e('Custom Field', 'woocommerce'); ?> <span class="required">*</span></label>
                        <input id="<?php echo esc_attr($this->id); ?>-custom-field" class="input-text" type="text" autocomplete="off">
                    </p>
                </fieldset>
                <?php
            }

            // Payment processing
            public function process_payment($order_id) {
                $order = wc_get_order($order_id);

                // Mark as on-hold (we're awaiting the payment)
                $order->update_status('on-hold', __('Awaiting custom payment', 'woocommerce'));

                // Reduce stock levels
                wc_reduce_stock_levels($order_id);

                // Remove cart
                WC()->cart->empty_cart();

                // Return thank you page redirect
                return array(
                    'result' => 'success',
                    'redirect' => $this->get_return_url($order)
                );
            }
        }
    }

    // Add to WooCommerce
    add_filter('woocommerce_payment_gateways', 'add_my_custom_payment_gateway');
    function add_my_custom_payment_gateway($gateways) {
        $gateways[] = 'WC_Gateway_Custom';
        return $gateways;
    }

    // Enqueue JavaScript file
    add_action('wp_enqueue_scripts', 'custom_gateway_enqueue_script');
    function custom_gateway_enqueue_script() {
        wp_enqueue_script('custom-gateway-js', plugin_dir_url(__FILE__) . 'custom-gateway.js', array('jquery'), '1.0', true);
    }
}
?>

问题排查与修复方案 #

1. 补充is_available()核心方法 #

WooCommerce依赖这个方法判断网关是否能在结账页面显示，你的代码未实现该方法，默认会返回false，导致网关不显示。
在WC_Gateway_Custom类中添加以下方法：

public function is_available() {
    // 仅当网关启用且订单金额大于0时显示
    return $this->get_option('enabled') === 'yes' && WC()->cart->total > 0;
}

2. 完善WooCommerce激活检测逻辑 #

当前代码只检测了普通插件激活场景，未考虑WooCommerce作为多站点网络插件激活的情况，替换原有的激活检测代码：

// 替换原有的WooCommerce激活检测代码
if ( ! function_exists( 'is_plugin_active_for_network' ) ) {
    require_once( ABSPATH . '/wp-admin/includes/plugin.php' );
}
$woocommerce_active = in_array( 'woocommerce/woocommerce.php', apply_filters( 'active_plugins', get_option( 'active_plugins' ) ) ) || ( is_multisite() && is_plugin_active_for_network( 'woocommerce/woocommerce.php' ) );

if ( $woocommerce_active ) {
    // 原有的网关初始化、钩子注册等代码放在这里
}

3. 调整plugins_loaded钩子优先级 #

当前优先级设为5，可能早于WooCommerce的初始化时机，导致网关类无法被正确识别，修改优先级为20：

add_action('plugins_loaded', 'my_custom_payment_gateway_init', 20);

4. 再次确认后台启用状态 #

进入WooCommerce设置→支付选项，检查自定义网关的「启用/禁用」复选框是否已勾选，即使默认值是yes，也需确认后台实际配置是否生效。

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