WordPress中点击操作时始终保留?ref={username} URL参数（含跨域）

针对你遇到的问题——全站导航（含跨域名跳转）保留?ref={username}参数，且不能使用add_query_var()的情况，以下是分场景的具体实现代码：

1. 全局获取Referral参数（复用函数） #

先写一个通用函数，用于获取当前的ref参数（优先从URL取，没有则从Cookie取，同时将参数存入Cookie避免刷新丢失）：

// 全局获取并存储referral参数
function get_current_referral() {
    $ref = '';
    // 优先读取URL中的ref/r参数
    if ( isset( $_GET['ref'] ) ) {
        $ref = sanitize_text_field( $_GET['ref'] );
    } elseif ( isset( $_GET['r'] ) ) {
        $ref = sanitize_text_field( $_GET['r'] );
    }
    // 将参数存入Cookie，有效期30天
    if ( $ref ) {
        setcookie( 'site_referral', $ref, time() + 30*24*60*60, COOKIEPATH, COOKIE_DOMAIN );
    } else {
        // URL无参数时，从Cookie读取
        $ref = isset( $_COOKIE['site_referral'] ) ? sanitize_text_field( $_COOKIE['site_referral'] ) : '';
    }
    return $ref;
}

2. 站内链接自动添加ref参数 #

针对WordPress原生的文章、页面、分类、菜单等链接，使用对应过滤器自动追加参数：

// 文章/页面链接添加ref参数
add_filter( 'post_type_link', 'add_referral_to_post_links', 10, 2 );
function add_referral_to_post_links( $url, $post ) {
    $ref = get_current_referral();
    return $ref ? add_query_arg( 'ref', $ref, $url ) : $url;
}

// 分类/标签链接添加ref参数
add_filter( 'term_link', 'add_referral_to_term_links', 10, 3 );
function add_referral_to_term_links( $url, $term, $taxonomy ) {
    $ref = get_current_referral();
    return $ref ? add_query_arg( 'ref', $ref, $url ) : $url;
}

// 搜索结果链接添加ref参数
add_filter( 'search_link', 'add_referral_to_search_link' );
function add_referral_to_search_link( $url ) {
    $ref = get_current_referral();
    return $ref ? add_query_arg( 'ref', $ref, $url ) : $url;
}

// 自定义菜单链接添加ref参数（支持站内/跨域名）
add_filter( 'nav_menu_link_attributes', 'add_referral_to_menu_links', 10, 3 );
function add_referral_to_menu_links( $atts, $item, $args ) {
    $ref = get_current_referral();
    if ( $ref && !empty( $atts['href'] ) ) {
        // 如需给跨域名链接也加参数，直接移除下面的if判断
        if ( strpos( $atts['href'], home_url() ) === 0 || strpos( $atts['href'], '/' ) === 0 ) {
            $atts['href'] = add_query_arg( 'ref', $ref, $atts['href'] );
        }
    }
    return $atts;
}

3. Bricks Builder元素链接处理 #

针对Bricks的按钮、文本链接等元素，修改其渲染后的HTML以追加参数：

// 给Bricks按钮、链接元素添加ref参数
add_filter( 'bricks/frontend/render_element', 'add_referral_to_bricks_elements', 10, 2 );
function add_referral_to_bricks_elements( $element_html, $element ) {
    $ref = get_current_referral();
    if ( !$ref ) return $element_html;

    // 处理按钮元素
    if ( $element->name === 'button' ) {
        $link = $element->settings['link']['url'] ?? '';
        if ( $link ) {
            $new_link = add_query_arg( 'ref', $ref, $link );
            $element_html = str_replace( $link, $new_link, $element_html );
        }
    }

    // 处理文本链接元素
    if ( $element->name === 'link' ) {
        $link = $element->settings['url'] ?? '';
        if ( $link ) {
            $new_link = add_query_arg( 'ref', $ref, $link );
            $element_html = str_replace( $link, $new_link, $element_html );
        }
    }

    // 如需处理其他Bricks元素，可在此添加判断
    return $element_html;
}

4. 所有重定向跳转添加ref参数 #

针对使用wp_redirect()的跳转（如表单提交、自定义重定向），自动追加参数：

// 给wp_redirect跳转添加ref参数
add_filter( 'wp_redirect', 'add_referral_to_redirects', 10, 2 );
function add_referral_to_redirects( $location, $status ) {
    $ref = get_current_referral();
    return $ref ? add_query_arg( 'ref', $ref, $location ) : $location;
}

关键说明 #

• 为何不用add_query_var()：该函数会将ref注册为WordPress公共查询变量，与你已配置的/blog永久链接结构冲突，导致跳转异常。我们通过钩子手动追加参数，不会影响原有永久链接规则。
• Cookie存储的作用：确保用户刷新页面、关闭浏览器后重新访问时，仍能保留ref参数（无需依赖URL中的参数）。
• 跨域名支持：如需给外部域名链接也添加参数，只需移除菜单钩子中的站内链接判断即可。

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