WordPress函数：sanitize_title：将字符串转换为安全的URL别名

简介

sanitize_title 函数是WordPress的“字符串净化器”，它能将任何给定的字符串（如文章标题）处理成符合URL规范、全小写、仅包含数字字母和连字符的“别名”，常用于生成文章、页面、分类的固定链接。

语法

该函数定义于 wp-includes/formatting.php 文件中。它内部调用了多个核心的字符串处理函数，如 remove_accents 和 sanitize_title_with_dashes。

函数签名：

sanitize_title( string $title, string $fallback_title = '', string $context = 'save' ): string

参数与返回值说明：

用法

基础用法

最常见场景是手动为文章或自定义文章类型生成别名，用于构建URL或存储到数据库。

// 示例：手动生成一个文章的别名
$raw_title = 'Hello World & Good Morning!';
$sanitized_slug = sanitize_title( $raw_title );

echo $raw_title; // 输出：Hello World & Good Morning!
echo $sanitized_slug; // 输出：hello-world-good-morning

// 在实际开发中，你可能这样使用它来创建自定义查询或存储
$args = array(
    'post_type' => 'my_custom_post',
    'name' => $sanitized_slug // 使用净化后的别名进行精确查询
);
$post = get_posts( $args );

为什么WordPress不直接使用原始标题？ 因为URL必须是一串标准字符，空格、中文、标点符号、大写字母等都需要被统一、安全地转换，这确保了链接的兼容性和可读性。

进阶用法

在开发插件或主题时，你可能需要基于用户输入或其他动态内容创建唯一的分类或术语别名。

// 示例：动态创建分类项并确保别名有效
$user_input_category_name = $_POST['new_category']; // 假设用户输入为 “My Cat’s Toys & More”

// 重要：在操作前，始终验证和清理原始用户输入。
if ( ! empty( $user_input_category_name ) ) {
    $clean_name = sanitize_text_field( $user_input_category_name ); // 先进行基础文本净化
    $category_slug = sanitize_title( $clean_name );

    // 检查别名是否已存在，避免冲突
    if ( ! term_exists( $category_slug, 'category' ) ) {
        wp_insert_term(
            $clean_name, // 使用净化后的名称作为显示名
            'category',
            array(
                'slug' => $category_slug // 使用净化后的别名
            )
        );
    } else {
        // 处理重名逻辑，例如追加数字
        $counter = 1;
        while ( term_exists( $category_slug . '-' . $counter, 'category' ) ) {
            $counter++;
        }
        $category_slug = $category_slug . '-' . $counter;
        // ... 插入新分类
    }
}

为什么这里先用 sanitize_text_field？ 因为 sanitize_title 的职责是生成别名，它不负责移除所有可能有害的代码（如<script>）。sanitize_text_field 会做更严格的文本清理，两者结合是处理用户输入的安全最佳实践。

易错点

对中文等非拉丁字符的处理

该函数默认会移除所有变音符号和非ASCII字符。对于纯中文标题，净化后可能得到空字符串。这时需要使用 $fallback_title 参数提供一个备选（如拼音或英文翻译），或使用 ‘query’ 上下文（它对特殊字符稍宽容）。更现代的解决方案是使用插件（如 wp-slug-translations）或自定义过滤钩子来生成友好的多语言别名。

与重写规则（Rewrite Rules）混淆

sanitize_title 只负责生成一个“纯净”的字符串，并不检查该字符串是否与现有的WordPress重写规则冲突。一个有效的别名（如 admin）仍可能因为与后台路径相同而导致页面无法访问。设置固定链接时应避免使用这些保留字。

误用于直接输出

此函数输出的是用于URL的字符串，它不负责对HTML进行转义。切勿将它的返回值直接echo到HTML页面中而不做处理。如果需要在页面上显示这个别名，应使用 esc_html 或 esc_attr 进行转义。

// 错误做法：直接输出，如果 $slug 包含 `&`，则会被浏览器解析为HTML实体。
echo '<a href="/product/' . sanitize_title( $product_name ) . '">Link</a>';

// 正确做法：使用 esc_url 或 esc_attr 包装URL部分。
echo '<a href="' . esc_url( '/product/' . sanitize_title( $product_name ) ) . '">Link</a>';
// 或仅输出别名文本
echo esc_html( sanitize_title( $product_name ) );

最佳实践

理解其限制与机制

了解 sanitize_title 会将空格转为连字符、移除特殊字符、全部转为小写。这意味着 The Price is $100 会变成 the-price-is-100。在开发多语言或需要保留大小写的网站时，可能需要通过 sanitize_title 过滤器来定制逻辑。

始终对原始输入进行安全处理

sanitize_title 是处理流程中的一环，而非起点。当处理来自用户（前端表单、REST API等）的原始输入时，必须首先使用 sanitize_text_field、wp_unslash 或更具体的验证函数，然后再将其传入 sanitize_title。这遵循了“验证、清理、然后处理”的安全链条。

// 安全的数据处理流程示例
$unsafe_input = $_POST['title_from_form'];
// 1. 可选：移除魔术引号添加的斜杠（如果PHP设置开启了）
$clean_input = wp_unslash( $unsafe_input );
// 2. 清理文本，移除标签和多余空白
$clean_input = sanitize_text_field( $clean_input );
// 3. 验证是否为空或符合业务逻辑
if ( empty( $clean_input ) ) {
    wp_die( '标题不能为空。' );
}
// 4. 最后，生成安全的别名
$final_slug = sanitize_title( $clean_input );

避免不必要的重复调用

WordPress核心在保存文章、分类时已经自动调用过此函数生成别名（即 post_name）。在大多数情况下，你应从数据库（如 $post->post_name）中直接获取已净化的别名，而不是对文章标题重新处理。重复调用不仅是性能浪费，还可能因函数逻辑或过滤器的变化导致结果不一致。

结合现代开发模式

在使用WordPress REST API开发前端应用时，你通常不再需要手动调用此函数。相反，你应关注API端点的响应数据。例如，文章对象（/wp/v2/posts）的 slug 字段已经是净化后的结果。你的职责是安全地使用这个字段（例如，用 encodeURIComponent 在JavaScript中处理）来构建前端路由。