WooCommerce自定义order-received页面添同名参数引发404及PHP通知问题

问题背景 #

当使用自定义页面作为WooCommerce下单感谢页（页面slug为order-received），且URL中添加同名查询参数order-received=订单ID时，会触发404错误（示例URL：http://localhost/order-received/?order=269017&key=wc_order_09fU1jATKarrE&order-received=269017），同时抛出PHP通知：

Undefined index: order-received in /wp-content/plugins/woocommerce-subscriptions/vendor/woocommerce/subscriptions-core/includes/gateways/paypal/class-wcs-paypal.php on line 51

问题原因 #

1. 路由冲突：WooCommerce默认将order-received作为感谢页的端点路由，自定义页面使用相同slug后，URL中的同名查询参数会干扰WordPress的路由解析，导致404。
2. 参数未做存在性检查：WooCommerce Subscriptions的PayPal网关代码直接调用$_GET['order-received']，未先判断参数是否存在，因此触发未定义索引通知。

解决方案 #

1. 注册查询参数，避免路由冲突

添加以下代码到主题的functions.php文件或自定义插件中，让WordPress正确识别order-received查询参数：

add_filter('woocommerce_get_query_vars', 'register_order_received_query_var');
function register_order_received_query_var($query_vars) {
    $query_vars[] = 'order-received';
    return $query_vars;
}

2. 修复404错误

添加代码拦截请求，确保自定义感谢页在携带order-received参数时返回正常页面：

add_action('template_redirect', 'fix_custom_order_received_404');
function fix_custom_order_received_404() {
    if (is_page('order-received') && isset($_GET['order-received'])) {
        $order_id = absint($_GET['order-received']);
        // 验证订单ID有效性
        if ($order_id > 0 && wc_get_order($order_id)) {
            global $wp_query;
            $wp_query->is_404 = false;
            status_header(200);
        }
    }
}

3. 修复PHP未定义索引通知

添加代码提前处理参数，避免直接调用未定义的$_GET索引：

add_action('init', 'fix_wcs_paypal_order_received_notice');
function fix_wcs_paypal_order_received_notice() {
    // 若order-received参数不存在，尝试从order参数获取订单ID填充
    if (!isset($_GET['order-received'])) {
        $_GET['order-received'] = isset($_GET['order']) ? absint($_GET['order']) : '';
    }
}

4. 确认WooCommerce页面设置

进入WooCommerce后台设置：WooCommerce > 设置 > 高级 > 页面，将「订单已收到」选项选择为你的自定义order-received页面，确保系统正确关联感谢页。

注意事项 #

• 不要直接修改WooCommerce或Subscriptions的核心插件文件，避免更新时代码丢失。
• 测试前请备份主题functions.php文件或使用自定义插件添加代码，降低出错风险。

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