云策 WordPress 开发者社区

函数文档

wp_safe_redirect()

查看官方原文 ↗
💡 云策文档标注

概述

wp_safe_redirect() 函数用于执行安全的本地重定向，基于 wp_redirect() 实现。它通过检查目标主机是否在允许列表中，防止恶意重定向到外部主机，并默认回退到站点管理页面。

关键要点

  • 函数执行安全重定向，验证 $location 是否为允许的主机，否则重定向到默认的 wp-admin 页面。
  • 调用后需手动添加 exit; 以终止脚本执行，或结合 'wp_redirect' 和 'wp_redirect_status' 过滤器进行条件处理。
  • 参数包括 $location（必需，重定向路径或URL）、$status（可选，HTTP状态码，默认302）和 $x_redirect_by（可选，重定向应用标识，默认'WordPress'）。
  • 返回布尔值：重定向被取消时返回 false，否则返回 true。
  • 可通过 allowed_redirect_hosts 过滤器添加允许的主机域名。
  • 注意：在 AJAX 调用中 wp_safe_redirect() 可能无效，建议使用 JavaScript 进行重定向。
  • 为避免浏览器缓存重定向页面，建议在调用前使用 nocache_headers()。

代码示例

if ( wp_safe_redirect( $url ) ) {
    exit;
}

注意事项

  • 函数不会自动退出，必须手动调用 exit; 或使用条件语句。
  • 在 AJAX 上下文中，重定向应通过 JavaScript 实现，如 window.location.href。
  • 使用 nocache_headers() 可防止浏览器缓存重定向，避免意外行为。
📄 原文内容

Performs a safe (local) redirect, using wp_redirect() .

Description

Checks whether the $location is using an allowed host, if it has an absolute path. A plugin can therefore set or remove allowed host(s) to or from the list.

If the host is not allowed, then the redirect defaults to wp-admin on the siteurl instead. This prevents malicious redirects which redirect to another host, but only used in a few places.

Note: wp_safe_redirect() does not exit automatically, and should almost always be followed by a call to exit;:

wp_safe_redirect( $url );
exit;

Exiting can also be selectively manipulated by using wp_safe_redirect() as a conditional in conjunction with the ‘wp_redirect’ and ‘wp_redirect_status’ filters:

if ( wp_safe_redirect( $url ) ) {
    exit;
}

Parameters

$locationstringrequired
The path or URL to redirect to.
$statusintoptional
HTTP response status code to use. Default '302' (Moved Temporarily).

Default:302

$x_redirect_bystring|falseoptional
The application doing the redirect or false to omit. Default 'WordPress'.

Return

bool False if the redirect was canceled, true otherwise.

Source

function wp_safe_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' ) {

	// Need to look at the URL the way it will end up in wp_redirect().
	$location = wp_sanitize_redirect( $location );

	/**
	 * Filters the redirect fallback URL for when the provided redirect is not safe (local).
	 *
	 * @since 4.3.0
	 *
	 * @param string $fallback_url The fallback URL to use by default.
	 * @param int    $status       The HTTP response status code to use.
	 */
	$fallback_url = apply_filters( 'wp_safe_redirect_fallback', admin_url(), $status );

	$location = wp_validate_redirect( $location, $fallback_url );

	return wp_redirect( $location, $status, $x_redirect_by );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_safe_redirect_fallback’, string $fallback_url, int $status )

Filters the redirect fallback URL for when the provided redirect is not safe (local).

Uses Description
wp_sanitize_redirect()wp-includes/pluggable.php

Sanitizes a URL for use in a redirect.
wp_validate_redirect()wp-includes/pluggable.php

Validates a URL for use in a redirect.
wp_redirect()wp-includes/pluggable.php

Redirects to another page.
admin_url()wp-includes/link-template.php

Retrieves the URL to the admin area for the current site.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 2 moreShow less

Used by Description
WP_Sitemaps::redirect_sitemapxml()wp-includes/sitemaps/class-wp-sitemaps.php

Redirects a URL to the wp-sitemap.xml
WP_Recovery_Mode::redirect_protected()wp-includes/class-wp-recovery-mode.php

Redirects the current request to allow recovering multiple errors in one go.
WP_Recovery_Mode::handle_exit_recovery_mode()wp-includes/class-wp-recovery-mode.php

Handles a request to exit Recovery Mode.
set_screen_options()wp-admin/includes/misc.php

Saves option for number of rows when listing posts, pages, comments, etc.
Custom_Background::take_action()wp-admin/includes/class-custom-background.php

Executes custom background modification.

Changelog

Version Description
5.1.0 The return value from wp_redirect() is now passed on, and the $x_redirect_by parameter was added.
2.3.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    KZeni


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    As with wp_redirect, unless this is patched to perform this natively in the future, be sure to include nocache_headers(); before the wp_safe_redirect if you want to make sure the visitor’s browser doesn’t cache the redirect page result (can even happen when this is set to use a 302 redirect) which may cause the redirect to happen for longer than desired.

    For example, this can be problematic when used to redirect to a login page when trying to access protected content since the visitor can then log in to find that they’re still taken back to the login page when trying to go back to that page they were trying to go to due to the redirect having been potentially cached by their web browser (again, even with it being a 302 redirect.) Having nocache_headers(); before the redirect prevents this potential issue.

  3. Skip to note 6 content


    capbussat


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Just for imformation wp_safe_redirect or wp_redirect does not work from an ajax call. I think this answer can help others:

    I have used a function to redirect from a JS AJAX call. First, it sets some values to database and then tries to redirect in this way:

    if (wp_safe_redirect( $url))

exit();

    But it just returns same page followed by ‘undefined’.

    I finally solved directly the redirection part in JS:

     window.location.href = url; // keeps page history

    Works also :

      window.location.replace( url ); // cleans page history