WordPress函数：esc_url：净化与校验URL

简介

esc_url 函数用于对URL进行净化和编码，确保其在HTML上下文或属性中安全输出，是处理用户输入URL、防止跨站脚本（XSS）攻击的关键安全函数。

语法

函数定义于 wp-includes/formatting.php 文件中。其内部主要调用了 wp_kses_bad_protocol() 函数来移除危险协议，并使用 _wp_translate_php_url_extension_to_css() 处理特定转换。

esc_url( string $url, array $protocols = null, string $_context = 'display' ): string

返回值：净化后的URL字符串。如果输入为空或解析后无有效协议，则返回空字符串。

用法

基础用法

最常见的场景是在模板文件中输出一个来自数据库或用户输入的链接，例如文章的自定义字段。

<?php
// 假设从自定义字段获取一个可能的用户输入URL
$external_link = get_post_meta( get_the_ID(), 'external_link', true );

// 在HTML属性中安全地输出此URL
?>
<a href="<?php echo esc_url( $external_link ); ?>" rel="noopener noreferrer">
    访问链接
</a>

为什么这样做？ 直接将未净化的 $external_link 输出到 href 属性中极其危险。恶意用户可能输入如 javascript:alert('xss') 或包含双引号破坏属性的URL。esc_url 会剥离 javascript: 等危险协议，并对特殊字符进行编码，确保它只是一个无害的链接。

进阶用法

在动态生成重定向链接或处理带有复杂查询参数的URL时，确保整个URL的合法性。

<?php
// 动态构建一个重定向URL，包含查询参数
$redirect_to = 'https://example.com/wp-login.php';
$query_args = array(
    'redirect_to' => admin_url( 'edit.php' ),
    'action'      => 'some_action',
);
$login_url = add_query_arg( $query_args, $redirect_to );

// 即使用add_query_arg构建，也应在输出前净化
wp_redirect( esc_url_raw( $login_url ) );
exit;

注意这里使用了 esc_url_raw：wp_redirect 函数需要一个未进行HTML实体编码的原始URL。esc_url_raw 与 esc_url 核心净化逻辑相同，但默认在 'db' 上下文中运行，避免对 & 等字符进行过度编码，使其适合用于HTTP头或数据库存储。

易错点

对已存储的安全数据重复转义

错误做法是，从数据库获取一个已经过 esc_url 处理并安全存储的URL，在输出时再次转义。

// 假设 $safe_url 是已经净化后存入数据库的值
$safe_url = get_option( 'my_safe_url' );
// 错误：会导致双重编码，`&` 可能变成 `&`
echo '<a href="' . esc_url( $safe_url ) . '">Link</a>';

原因：存储在数据库中的URL应是“原始”数据。转义（esc_url, esc_html 等）应发生在输出时刻，而非存储时刻。存储时只需使用 sanitize_text_field 等清理函数。

误认为esc_url能验证URL可达性

esc_url 仅进行语法层面的净化和协议白名单检查，并不检查该URL是否真实存在、可达或返回HTTP 200状态码。

$url = 'https://一个不存在的网站.com/page';
// 这行代码会正常执行，输出净化后的URL，但该链接点击后无法访问
echo esc_url( $url );

在非HTML属性上下文中使用

esc_url 的编码是为HTML属性（如 href、src）设计的。如果需要在纯文本、JavaScript或CSS中输出URL，应使用其他专门的转义函数。

// 错误：在JavaScript字符串中使用esc_url不够充分
$js_url = esc_url( $user_input );
echo '<script>var myUrl = "' . $js_url . '";</script>'; // 仍有XSS风险

// 正确：使用专门针对JS上下文的转义函数
$js_url = esc_js( $user_input ); // 或 wp_json_encode
echo '<script>var myUrl = "' . $js_url . '";</script>';

忽略rel=”noopener noreferrer”

这是一个与安全相关的最佳实践，常与 esc_url 搭配使用。当链接目标为 _blank 时，必须添加以防范性能和安全漏洞。

// 不够安全
echo '<a href="' . esc_url( $url ) . '" target="_blank">打开</a>';

// 最佳实践：添加rel属性
echo '<a href="' . esc_url( $url ) . '" target="_blank" rel="noopener noreferrer">打开</a>';

最佳实践

明确存储与输出的界限

遵循“输入时验证，存储时清理，输出时转义”的原则。
1. 接收用户输入时：使用 sanitize_text_field、sanitize_url（WP 5.5+）进行初步清理和存储。
2. 存储到数据库时：确保数据是“干净”的原始格式。
3. 从数据库取出并准备输出到前端时：使用 esc_url（用于HTML属性）或 esc_url_raw（用于重定向、API响应等）。

自定义允许的协议

如果您的站点功能需要支持WordPress默认白名单（wp_allowed_protocols）之外的协议（如 tel、skype、whatsapp），可以通过过滤器 'kses_allowed_protocols' 全局添加，或在调用 esc_url 时传入第二个参数。

// 为特定调用添加 `tel` 和 `sms` 协议
$phone_link = get_post_meta( get_the_ID(), 'phone_number', true );
$allowed_protocols = array( 'http', 'https', 'mailto', 'tel', 'sms' );
echo '<a href="' . esc_url( $phone_link, $allowed_protocols ) . '">拨打电话</a>';

在REST API或AJAX响应中

当通过WordPress REST API或Admin AJAX接口返回URL数据时，客户端可能是JavaScript应用。此时，不应在服务器端对URL进行HTML实体编码。

// 在REST API控制器或AJAX回调函数中
$data = array(
    // 使用 esc_url_raw 确保URL安全但未过度编码，便于客户端使用
    'link' => esc_url_raw( $raw_url ),
);
return rest_ensure_response( $data );

性能考量

esc_url 函数本身开销不高，但在循环中高频调用（如渲染数百个文章链接）时，若所有URL来源相同且确定安全，可考虑将净化后的结果缓存到变量中重复使用，避免完全相同的字符串被重复处理。

$base_url = 'https://cdn.example.com/';
$escaped_base_url = esc_url( $base_url ); // 缓存净化结果

foreach ( $images as $image ) {
    // 在循环中直接拼接已净化的部分
    echo '<img src="' . $escaped_base_url . esc_attr( $image['name'] ) . '">';
}