WordPress函数：wp_redirect 页面重定向

简介

wp_redirect 是 WordPress 中用于将用户浏览器安全地重定向到另一个页面的核心函数。它本质上包装并增强了 PHP 的 header('Location: …') 功能，在插件开发、表单提交处理和权限验证后的页面跳转等场景中必不可少。

语法

该函数定义于 wp-includes/pluggable.php 文件中。值得注意的是，pluggable.php 中的函数可以被插件重新定义（覆盖），但 wp_redirect 的核心逻辑通常已足够健壮，不建议轻易覆盖。

wp_redirect( string $location, int $status = 302, string $x_redirect_by = 'WordPress' ): bool

参数	类型	默认值	说明
`$location`	字符串	无	必需。要重定向至的 URL。此 URL 将被 `wp_sanitize_redirect()` 函数清理。
`$status`	整数	`302`	重定向的 HTTP 状态码。常用值：`301`（永久移动）， `302`（临时重定向）。
`$x_redirect_by`	字符串	`WordPress`	标识重定向发起者的字符串。可用于监控或过滤重定向来源。
返回值	布尔值		如果重定向成功设置（仅设置 header，未终止脚本），返回 `true`。失败则返回 `false`。

用法

基础用法

最常见的场景是在处理完某个逻辑（如保存表单数据）后，将用户带到一个成功或提示页面。最关键的原则是：调用 wp_redirect() 前不能有任何内容（包括空格、HTML 甚至 PHP 错误信息）发送到浏览器，否则会导致 “headers already sent” 错误。

// 示例：在主题的 functions.php 或插件文件中处理一个简单的表单提交
function my_handle_form_submission() {
    // 1. 首先检查是否是我们的表单提交动作
    if ( ! isset( $_POST[‘my_form_nonce’] ) || ! isset( $_POST[‘action’] ) || $_POST[‘action’] !== ‘my_form_action’ ) {
        return; // 不是我们的表单，直接退出
    }

    // 2. 验证安全随机数，防止跨站请求伪造攻击
    if ( ! wp_verify_nonce( $_POST[‘my_form_nonce’], ‘my_form_action’ ) ) {
        wp_die( ‘安全验证失败，请重试。’ );
    }

    // 3. 处理表单数据（此处仅为示例）
    $user_input = sanitize_text_field( $_POST[‘some_data’] );
    // ... 保存数据等操作 ...

    // 4. 所有处理完成，且未有输出，执行重定向
    // 使用 `esc_url_raw` 对 URL 进行严格清理，防止不安全的跳转
    $redirect_url = add_query_arg( ‘message’, ‘success’, home_url( ‘/thank-you/’ ) );
    wp_redirect( esc_url_raw( $redirect_url ) );

    // 5. 重定向后必须立即调用 exit 或 die() 终止脚本执行
    // **这是绝对必要的**，防止重定向后的代码继续运行，引发意外行为。
    exit;
}
// 将函数挂载到 `init` 或更早的动作钩子上，确保能在输出前处理
add_action( ‘init’, ‘my_handle_form_submission’ );

进阶用法

在某些场景下，你需要根据动态条件来决定重定向的目标。例如，用户登录后根据其角色重定向到不同仪表盘页面。

function my_redirect_after_login( $redirect_to, $request, $user ) {
    // $user 是一个 WP_User 对象
    if ( isset( $user->roles ) && is_array( $user->roles ) ) {
        // 如果是管理员，重定向到后台
        if ( in_array( ‘administrator’, $user->roles ) ) {
            return admin_url();
        }
        // 如果是编辑者，重定向到文章列表
        elseif ( in_array( ‘editor’, $user->roles ) ) {
            return admin_url( ‘edit.php’ );
        }
        // 其他用户，重定向到网站的特定会员页面
        else {
            return home_url( ‘/member-dashboard/’ );
        }
    }
    // 默认情况，返回原始的 $redirect_to
    return $redirect_to;
}
// 使用 `login_redirect` 过滤器，这是一个更优雅、专为登录重定向设计的方法
add_filter( ‘login_redirect’, ‘my_redirect_after_login’, 10, 3 );

为什么用过滤器而非直接使用 wp_redirect？ 在这个场景下，登录流程由 WordPress 核心控制，我们无法在合适的时机直接插入 wp_redirect() 和 exit。使用 login_redirect 过滤器是 WordPress 官方推荐的、介入此流程的标准方式，更安全、更可预测。

易错点

在已有输出后调用：这是最常见的错误。任何在 <?php 标签之前的空格、HTML 代码，甚至是 functions.php 文件末尾的 ?> 标签后的换行符，都算作输出。调用 wp_redirect() 前，必须确保处理逻辑位于所有输出之前，通常利用 init、wp_loaded 或 template_redirect 等早期动作钩子。
忘记终止脚本 (exit/die)：wp_redirect() 只发送 HTTP 头，不停止 PHP 执行。如果不在其后使用 exit;，后续代码仍会运行，可能导致重复提交、逻辑错误，甚至在极少数情况下使重定向失效。

使用不安全的用户输入作为重定向地址：直接使用 $_GET[‘redirect_to’] 或 $_POST[‘redirect_url’] 而不加验证和清理，会构成开放重定向漏洞，攻击者可利用此将用户引导至恶意网站。

// 危险！切勿直接使用未经验证的输入。
wp_redirect( $_GET[‘url’] );

// 正确做法：使用 `esc_url_raw()` 或 `wp_sanitize_redirect()` 进行清理。
$safe_url = esc_url_raw( $_GET[‘url’] );
wp_redirect( $safe_url );
exit;

混淆 HTTP 状态码：误用 301（永久移动）和 302（临时重定向）。对搜索引擎而言，301 意味着旧地址的权重将转移至新地址。如果你在进行临时性、状态性的跳转（如登录后、提交表单后），应使用 302。

最佳实践

优先使用 wp_safe_redirect 提升安全性

wp_safe_redirect() 是 wp_redirect() 的安全变体。它只允许重定向到与当前网站同主机（同域名）的 URL，或通过 allowed_redirect_hosts 过滤器明确允许的主机。这能有效防范开放重定向攻击。

// 安全做法：限制只能重定向到本站
wp_safe_redirect( home_url( ‘/secure-page/’ ) );
exit;

始终清理和验证重定向 URL

在动态构建重定向 URL，尤其是包含用户输入时，务必使用 esc_url_raw() 进行清理。如果涉及从数据库或外部 API 获取 URL，也应进行清理。

// 从设置选项获取 URL，并清理
$stored_url = get_option( ‘my_redirect_url’ );
wp_redirect( esc_url_raw( $stored_url ) );
exit;

合理使用 HTTP 状态码

301 Moved Permanently：用于网站永久性搬家、URL 结构永久变更。告知浏览器和搜索引擎更新书签和索引。
302 Found (或 303 See Other)：用于临时性跳转，如登录后、表单提交后、会话状态变化后。这是 wp_redirect() 的默认值，适用于大多数插件和主题开发场景。

利用过滤器和动作钩子实现优雅重定向

不要总是试图“硬”插入 wp_redirect()。WordPress 为许多流程提供了专用的过滤器，使你的代码更符合架构、更易于被其他开发者扩展。
– 登录重定向：login_redirect 过滤器。
– 注销重定向：logout_redirect 过滤器。
– 评论提交后重定向：comment_post_redirect 过滤器。
– 使用 wp_redirect 钩子：wp_redirect 动作钩子允许你在重定向发生前修改 $location 和 $status。

确保 exit 位置的可靠性

将 exit; 或 die(); 紧跟在 wp_redirect() 之后。如果重定向逻辑在一个被多次调用的函数中，确保重定向逻辑有明确的提前返回（return;）机制，避免误执行 exit 导致主流程意外终止。对于挂载在钩子上的函数，重定向并 exit 通常是流程的终点。