深入理解 WordPress `wp_redirect()` 函数的源码：如何发送 `Location` 头信息进行重定向。

大家好，我是你们今天的 WordPress 源码解读小导游。今天咱们要聊聊 WordPress 里的一个“传送门”—— wp_redirect() 函数。别害怕，源码没那么可怕，咱们慢慢来，保证让大家听得懂，还能乐呵乐呵！

一、 wp_redirect()：你的 WordPress 小传送门

wp_redirect()，顾名思义，就是用来重定向的。想象一下，你兴高采烈地访问了一个网页，结果服务器告诉你：“哎呀，这个页面搬家了，请去新地址！” 这就是重定向在起作用。wp_redirect() 在 WordPress 里就扮演着这个角色，它可以将用户从一个 URL 悄无声息地“传送”到另一个 URL。

二、 源码探秘：wp-includes/functions.php 中的秘密

好了，现在让我们钻到源码里看看 wp_redirect() 到底是怎么工作的。打开你的 WordPress 安装目录，找到 wp-includes/functions.php 文件。用你喜欢的文本编辑器打开它，搜索 wp_redirect。你会看到类似这样的代码：

function wp_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' ) {
    global $is_IIS;

    $location = wp_sanitize_redirect( $location );

    /**
     * Filters the redirect location.
     *
     * @since 2.1.0
     *
     * @param string $location The path to redirect to.
     * @param int    $status   The HTTP response status code to use.
     */
    $location = apply_filters( 'wp_redirect', $location, $status );

    /**
     * Filters the redirect status code.
     *
     * @since 2.5.0
     *
     * @param int    $status   The HTTP response status code to use.
     * @param string $location The path to redirect to.
     */
    $status = apply_filters( 'wp_redirect_status', $status, $location );

    if ( wp_doing_ajax() ) {
        /**
         * Fires when a redirect is called during an AJAX request.
         *
         * @since 4.4.0
         *
         * @param string $location The path to redirect to.
         * @param int    $status   The HTTP response status code to use.
         */
        do_action( 'wp_redirect_ajax_response', $location, $status );
        return true;
    }

    if ( headers_sent() ) {
        return false;
    }

    if ( ! wp_validate_redirect( $location ) ) {
        return false;
    }

    $status = absint( $status );
    if ( ( $status < 300 || $status > 399 ) && $status !== 503 ) {
        $status = 302;
    }

    $location = wp_get_location_header( $location );

    if ( $is_IIS ) {
        header( 'Refresh: 0;url=' . $location );
    } else {
        header( 'Location: ' . $location, true, $status );
    }

    return true;
}

三、 代码解读：一行一行扒给你看

别被这堆代码吓跑，咱们一点一点地分析。

1. 函数签名：function wp_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' )

   • $location：这是目标 URL，也就是你要把用户“传送”到的地方。必须是字符串类型
   • $status：这是 HTTP 状态码，告诉浏览器这次重定向的类型。默认值是 302，表示“临时重定向”。
   • $x_redirect_by：这是一个可选参数，用于设置 X-Redirect-By HTTP 头部，表明重定向是由 WordPress 发起的。这个参数在后续的代码中实际上并没有被使用，可能在早期版本中有相关逻辑，但现在已经被废弃。

2. $location = wp_sanitize_redirect( $location );

   • 这一行调用了 wp_sanitize_redirect() 函数，对 $location 进行清理，防止恶意代码注入，确保重定向的安全性。

3. apply_filters( 'wp_redirect', $location, $status ); 和 apply_filters( 'wp_redirect_status', $status, $location );

   • 这两行使用了 WordPress 的钩子机制。apply_filters() 允许插件或主题修改重定向的 URL 和状态码。如果你想自定义重定向行为，可以通过这两个钩子来实现。

4. if ( wp_doing_ajax() ) { ... }

   • 这个条件判断检查当前是否是 AJAX 请求。如果是 AJAX 请求，则触发 wp_redirect_ajax_response action，通常 AJAX 请求不应该直接发送 HTTP 重定向头，而是通过 JavaScript 来处理。

5. if ( headers_sent() ) { return false; }

   • 这是一个非常重要的检查！headers_sent() 函数检查 HTTP 头部是否已经发送。如果头部已经发送，就不能再发送重定向头部了，否则会报错。所以，wp_redirect() 必须在任何输出之前调用。

6. if ( ! wp_validate_redirect( $location ) ) { return false; }

   • 这个条件判断调用 wp_validate_redirect() 函数来验证 $location 是否是有效的重定向 URL。这个函数会检查 URL 是否在允许的域名列表中，以防止重定向到恶意网站。

7. $status = absint( $status ); 和 if ( ( $status < 300 || $status > 399 ) && $status !== 503 ) { $status = 302; }

   • 这两行代码确保 $status 是一个有效的 HTTP 状态码。首先，absint() 将 $status 转换为绝对整数。然后，它检查 $status 是否在 300-399 之间（重定向状态码的范围），或者是否等于 503（服务不可用）。如果 $status 不在这些范围内，就将其设置为默认值 302。

8. $location = wp_get_location_header( $location );

   • 这个函数用来处理 URL 中的特殊字符，确保 URL 可以正确地作为 HTTP 头部发送。

9. if ( $is_IIS ) { header( 'Refresh: 0;url=' . $location ); } else { header( 'Location: ' . $location, true, $status ); }

   • 这是核心代码！这里使用 header() 函数发送 HTTP 头部，实现重定向。
     • 对于 IIS 服务器，使用 Refresh 头部进行重定向。
     • 对于其他服务器，使用 Location 头部进行重定向，true 参数表示强制替换之前的 Location 头部，$status 参数设置 HTTP 状态码。

10. return true;

    • 函数执行成功，返回 true。

四、 header() 函数：幕后英雄

header() 函数是 PHP 内置的函数，用于发送 HTTP 头部。HTTP 头部是服务器与浏览器之间传递信息的关键。其中，Location 头部告诉浏览器要重定向到的 URL。

header('Location: ' . $location, true, $status); 这行代码就是 wp_redirect() 实现重定向的关键。

• 'Location: ' . $location：设置 Location 头部，指定目标 URL。
• true：强制替换之前的 Location 头部。
• $status：设置 HTTP 状态码。

五、 HTTP 状态码：重定向的类型

HTTP 状态码告诉浏览器重定向的类型。常见的重定向状态码有：

状态码	含义	适用场景
301	永久重定向 (Moved Permanently)	网站域名变更、页面永久迁移
302	临时重定向 (Found)	页面临时维护、A/B 测试
307	临时重定向 (Temporary Redirect)	与 302 类似，但要求请求方法不变
308	永久重定向 (Permanent Redirect)	与 301 类似，但要求请求方法不变
503	服务不可用 (Service Unavailable) (虽然不是重定向状态码，但是有时候用在重定向场景)	网站维护、服务器过载，可以将用户重定向到维护页面

wp_redirect() 默认使用 302 状态码，表示临时重定向。如果你的页面是永久迁移，应该使用 301 状态码。

六、 使用场景举例：让 wp_redirect() 飞起来

1. 登录后重定向：

   if ( isset( $_POST['username'] ) && isset( $_POST['password'] ) ) {
       // 验证用户名和密码
       if ( $_POST['username'] == 'admin' && $_POST['password'] == 'password' ) {
           // 登录成功，重定向到管理页面
           wp_redirect( admin_url() );
           exit; // 确保后续代码不再执行
       } else {
           // 登录失败，显示错误信息
           echo '用户名或密码错误';
       }
   }

2. 根据用户角色重定向：

   global $current_user;
   get_currentuserinfo();
   
   if ( in_array( 'administrator', $current_user->roles ) ) {
       // 管理员，重定向到管理页面
       wp_redirect( admin_url() );
       exit;
   } elseif ( in_array( 'editor', $current_user->roles ) ) {
       // 编辑，重定向到编辑页面
       wp_redirect( admin_url( 'edit.php' ) );
       exit;
   } else {
       // 其他用户，重定向到首页
       wp_redirect( home_url() );
       exit;
   }

3. 处理表单提交后重定向：

   if ( isset( $_POST['submit'] ) ) {
       // 处理表单数据
       // ...
   
       // 重定向到成功页面
       wp_redirect( home_url( '/success/' ) );
       exit;
   }

七、 注意事项：避开雷区

1. 在输出之前调用：

   • wp_redirect() 必须在任何输出之前调用，否则会报错。
   • 这意味着不能在 echo、print、HTML 标签等之后调用 wp_redirect()。

2. 使用 exit; 终止脚本执行：

   • 在 wp_redirect() 之后，必须使用 exit; 终止脚本执行，防止后续代码继续执行，导致意外结果。

3. 检查 headers_sent()：

   • 在调用 wp_redirect() 之前，最好先检查 headers_sent()，确保 HTTP 头部尚未发送。

4. 验证 URL：

   • 使用 wp_validate_redirect() 验证 URL，防止重定向到恶意网站。

5. 处理 AJAX 请求：

   • 在 AJAX 请求中，不要直接使用 wp_redirect()，而是通过 JavaScript 来处理重定向。

八、 深入挖掘：相关函数和钩子

• wp_sanitize_redirect()： 清理 URL，防止恶意代码注入。
• wp_validate_redirect()： 验证 URL，防止重定向到恶意网站。
• wp_get_location_header()： 处理 URL 中的特殊字符。
• wp_redirect 过滤器： 修改重定向的 URL。
• wp_redirect_status 过滤器： 修改重定向的状态码。
• wp_redirect_ajax_response action： 在 AJAX 请求中处理重定向。

九、 总结：掌握 WordPress 的传送秘术

wp_redirect() 是 WordPress 中一个非常重要的函数，用于实现重定向。通过理解 wp_redirect() 的源码，我们可以更好地掌握 WordPress 的重定向机制，并在开发中灵活运用。记住，要在输出之前调用 wp_redirect()，使用 exit; 终止脚本执行，并验证 URL 的安全性。

希望今天的讲座能帮助大家深入理解 wp_redirect() 函数。下次再见！