自定义WooCommerce支付网关适配Blocks结账：编辑页可见但实际页不显示

我开发了一个自定义支付网关，正在通过新增类适配WooCommerce的新Blocks结账功能。目前在WordPress结账页面的编辑界面里能正常看到该支付方式，但实际结账时却不显示。

编辑结账页面（添加Blocks支持类后可见支付方式） #

实际结账页面（支付方式不显示） #

已添加的Blocks结账支持代码 #

add_action( 'before_woocommerce_init', 'portone_cart_checkout_blocks_compatibility' );

function portone_cart_checkout_blocks_compatibility() {

    if( class_exists( '\Automattic\WooCommerce\Utilities\FeaturesUtil' ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'cart_checkout_blocks',
            __FILE__,
            false // true (compatible, default) or false (not compatible)
        );
    }

}

add_action( 'woocommerce_blocks_loaded', 'portone_gateway_block_support' );
function portone_gateway_block_support() {

     if( ! class_exists( 'Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType' ) ) {
        return;
     }

    // 引入网关Block支持类
    require_once plugin_dir_path( __FILE__ ) . 'includes/portoneBlocks.php';

    // 注册刚引入的PHP类
    add_action(
        'woocommerce_blocks_payment_method_type_registration',
        function( Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry $payment_method_registry ) {
            $payment_method_registry->register( new WC_Portone_Gateway_Blocks_Support );
        }
    );

}

排查与解决步骤 #

1. 修正兼容性声明
   你在declare_compatibility里把兼容性设成了false，这会告诉WooCommerce你的网关不支持Blocks结账，必须改成true：

   \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
       'cart_checkout_blocks',
       __FILE__,
       true // 改为true声明兼容
   );
   

2. 检查WC_Portone_Gateway_Blocks_Support类的实现
   这个类必须正确继承AbstractPaymentMethodType，并实现核心方法：

   • initialize()：初始化网关设置
   • is_active()：返回网关是否启用的判断逻辑，确保符合结账场景的激活条件
   • get_payment_method_script_handles()：注册前端JS脚本，Blocks结账依赖前端渲染支付选项
   • get_payment_method_data()：传递前端需要的网关配置（标题、描述等）

   类的基础实现示例：

   class WC_Portone_Gateway_Blocks_Support extends \Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType {
       protected $name = 'portone'; // 必须和你的网关ID一致
   
       public function initialize() {
           $this->settings = get_option( 'woocommerce_portone_settings', array() );
       }
   
       public function is_active() {
           return isset( $this->settings['enabled'] ) && 'yes' === $this->settings['enabled'];
       }
   
       public function get_payment_method_script_handles() {
           wp_register_script(
               'portone-blocks-support',
               plugins_url( 'assets/js/portone-blocks.js', __FILE__ ),
               array( 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-i18n' ),
               '1.0.0', // 生产环境使用固定版本号
               true
           );
           return array( 'portone-blocks-support' );
       }
   
       public function get_payment_method_data() {
           return array(
               'title' => $this->settings['title'],
               'description' => $this->settings['description'],
           );
       }
   }
   

3. 补充前端JS脚本
   必须编写对应的前端脚本（如示例中的portone-blocks.js），注册支付方式并渲染UI：

   const { registerPaymentMethod } = window.wc.wcBlocksRegistry;
   const { createElement } = window.wp.element;
   
   const PortonePaymentComponent = () => {
       return createElement(
           'div',
           { className: 'wc-payment-method portone-payment-method' },
           createElement('input', {
               type: 'radio',
               name: 'payment_method',
               value: 'portone',
               id: 'payment_method_portone'
           }),
           createElement('label', { htmlFor: 'payment_method_portone' }, window.wcSettings.paymentMethods.portone.title)
       );
   };
   
   registerPaymentMethod({
       name: 'portone', // 和PHP类的name一致
       label: window.wcSettings.paymentMethods.portone.title,
       content: createElement(PortonePaymentComponent),
       edit: createElement(PortonePaymentComponent),
       canMakePayment: () => true, // 可根据业务逻辑添加判断条件
       ariaLabel: window.wcSettings.paymentMethods.portone.title,
   });
   

4. 清除缓存
   修改代码后，清除WordPress缓存、WooCommerce缓存以及浏览器缓存，确保新配置生效。

5. 检查网关基础设置
   确认自定义支付网关在WooCommerce后台已启用，且没有设置限制显示的条件（如最低订单金额、指定国家/地区），这些条件需要同步适配Blocks结账场景。

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