启用WooCommerce HPOS同步后结账自定义字段丢失求助

问题背景 #

在WooCommerce的/checkout页面添加了名为「Link (Facebook/Zalo/Telegram)」的自定义必填字段，未启用HPOS时可正常在后台订单查看字段内容。但启用HPOS并勾选「Enable compatibility mode (synchronizes orders to the posts table)」，完成订单同步后，所有订单的该自定义字段内容全部丢失。

问题根源 #

原有代码使用update_post_meta和get_post_meta操作订单元数据，这是针对传统订单存储（作为post类型）的方法。HPOS将订单存储在独立的自定义数据库表中，兼容模式同步时不会自动将post meta迁移到HPOS的订单元数据，且新订单也应使用WooCommerce官方的订单元数据API，而非post相关函数。

修改后的完整代码 #

// 显示结账自定义字段
add_action('woocommerce_after_checkout_billing_form', 'custom_checkout_field');
function custom_checkout_field($checkout) {
    $key_field = '_fbhoaczalo'; // 统一使用带下划线的元键，符合WooCommerce规范
    echo '<div id="custom_checkout_field">';
    woocommerce_form_field('fbhoaczalo', array(
        'type' => 'textarea',
        'id' => 'fb_zalo',
        'class' => array('my-field-class form-row-wide'),
        'label' => ('<strong style="color: #ffdf30;font-size: 120%;">Your contact [ <code>Facebook</code>, <code>Zalo</code>, <code>Telegram</code> ] :</strong>'),
        'required' => true,
        'placeholder' => ('This field is required'),
    ), $checkout->get_value('fbhoaczalo') ? $checkout->get_value('fbhoaczalo') : WC()->session->get('fbhoaczalo'));
    echo '</div>';
}

// 结账字段验证
add_action('woocommerce_checkout_process', 'customised_checkout_field_process');
function customised_checkout_field_process() {
    if (!$_POST['fbhoaczalo']) {
        wc_add_notice(__('This field cannot be blank. Please enter your contact information'), 'error');
    }
}

// 保存字段到WC Session并直接写入订单对象（HPOS兼容）
add_action('woocommerce_checkout_create_order', 'action_checkout_create_order', 10, 2);
function action_checkout_create_order($order, $data) {
    $field_key = 'fbhoaczalo';
    if (isset($_POST[$field_key])) {
        WC()->session->set($field_key, sanitize_textarea_field($_POST[$field_key]));
        $order->update_meta_data('_fbhoaczalo', sanitize_textarea_field($_POST[$field_key]));
    }
}

// 后台订单页面显示字段
add_action('woocommerce_admin_order_data_after_billing_address', 'codeastrology_show_new_checkout_field_order', 10, 1);
function codeastrology_show_new_checkout_field_order($order) {
    $contact_link = $order->get_meta('_fbhoaczalo');
    if ($contact_link) {
        echo '<p><strong>Link Facebook/Zalo/Tele:</strong> ' . esc_html($contact_link) . '</p>';
    }
}

// 订单邮件中显示字段
add_action('woocommerce_email_after_order_table', 'codeastrology_show_new_checkout_field_emails', 20, 4);
function codeastrology_show_new_checkout_field_emails($order, $sent_to_admin, $plain_text, $email) {
    $contact_link = $order->get_meta('_fbhoaczalo');
    if ($contact_link) {
        if ($plain_text) {
            echo 'Link Facebook/Zalo/Tele: ' . esc_html($contact_link) . "\n";
        } else {
            echo '<p><strong>Link Facebook/Zalo/Tele:</strong> ' . esc_html($contact_link) . '</p>';
        }
    }
}

// 迁移旧订单的post meta到HPOS订单元数据（仅需执行一次，完成后可删除）
add_action('admin_init', 'migrate_old_contact_field_to_hpos');
function migrate_old_contact_field_to_hpos() {
    if (!current_user_can('manage_woocommerce') || !isset($_GET['migrate_contact_field'])) {
        return;
    }

    $args = array(
        'post_type' => 'shop_order',
        'posts_per_page' => -1,
        'post_status' => array_keys(wc_get_order_statuses()),
    );
    $orders = get_posts($args);

    foreach ($orders as $post) {
        $order = wc_get_order($post->ID);
        if (!$order) continue;

        $old_value = get_post_meta($post->ID, '_fbhoaczalo', true);
        if ($old_value && !$order->get_meta('_fbhoaczalo')) {
            $order->update_meta_data('_fbhoaczalo', $old_value);
            $order->save();
        }
    }

    wp_redirect(admin_url('admin.php?page=wc-orders'));
    exit;
}

关键改动说明 #

1. HPOS兼容的元数据操作：

   • 用$order->update_meta_data()替代update_post_meta，直接操作订单对象的元数据，适配HPOS存储结构
   • 用$order->get_meta()替代get_post_meta，从HPOS订单表中读取元数据

2. 代码精简与修复：

   • 移除冗余的post meta保存逻辑，统一在woocommerce_checkout_create_order中处理字段存储
   • 删除原代码中无效的用户元数据保存逻辑（$key_field = $key_field为错误写法）

3. 旧订单字段迁移：

   • 添加一次性迁移函数，执行方法：登录后台后访问https://你的域名/wp-admin/admin.php?page=wc-orders&migrate_contact_field，完成旧订单字段迁移后可删除该函数

4. 安全性优化：

   • 使用sanitize_textarea_field适配textarea字段的内容清理
   • 用esc_html输出字段内容，防止XSS攻击

操作步骤 #

1. 将原有自定义字段代码替换为上述代码
2. 执行旧订单字段迁移（仅针对已存在的旧订单）
3. 测试新下单流程，确认字段能正常保存并在后台和邮件中显示

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