WordPress函数：wp_kses_post：安全过滤文章内容HTML

简介

wp_kses_post 是 WordPress 用于安全过滤文章内容 HTML 标签的核心函数，它会在保留基本格式化标签的同时移除危险代码，主要用于输出需要保留部分 HTML 的用户输入内容，防止跨站脚本（XSS）攻击。

语法

该函数定义于 wp-includes/kses.php，内部调用 wp_kses() 并应用 'post' 规则集。

wp_kses_post( string $data ): string

参数说明：

返回值：返回过滤后的安全字符串，仅包含允许的HTML标签和属性。

用法

基础用法

最典型的场景是在主题模板中安全输出文章内容或自定义字段的HTML内容。这能防止用户输入中的恶意脚本执行，同时保留如 <strong>、<a>、<img> 等基础格式化标签。

<?php
// 在主题的 single.php 或内容输出处
$content = get_the_content();
// 直接输出过滤后的内容，允许文章格式化的HTML标签但移除危险代码
echo wp_kses_post( $content );
?>

进阶用法

处理来自自定义表单提交的富文本内容时，应在保存到数据库前进行过滤。虽然 WordPress 通常建议在输出时转义，但针对需要保留HTML的内容，提前过滤可确保数据库存储的数据本身是安全的。

<?php
// 处理自定义表单提交的富文本描述
if ( isset( $_POST['user_bio'] ) && current_user_can( 'edit_posts' ) ) {
    // 首先进行基础的非空验证
    $raw_bio = sanitize_textarea_field( $_POST['user_bio'] );

    // 关键步骤：应用 wp_kses_post 过滤，允许安全的HTML标签
    $clean_bio = wp_kses_post( $raw_bio );

    // 安全地更新用户元数据
    update_user_meta( get_current_user_id(), 'custom_bio', $clean_bio );

    // 注意：此处输出时仍需考虑上下文转义
    // 如在HTML属性中使用，应使用 esc_attr()，而非直接输出
}
?>

易错点

混淆转义与过滤是常见错误。转义函数如 esc_html() 会将所有HTML标签转换为实体（如 < 变成 <），导致标签可见而非渲染。而 wp_kses_post() 是过滤，它会移除不允许的标签但保留允许的标签正常渲染。错误选择会导致内容显示异常或安全漏洞。

在错误的位置应用过滤可能导致数据污染。如果在数据存入数据库前已经过滤，那么数据库中存储的是“干净”的HTML。但如果在多个输出点都需要原始数据，则可能丢失信息。最佳实践取决于具体用例：如果确定数据仅用于特定HTML输出场景，提前过滤可提升性能；如果需要多用途，则存储原始数据并在输出时过滤。

过度依赖导致性能问题。wp_kses_post() 涉及复杂的HTML解析和规则匹配，在循环中频繁处理大量内容（如输出百篇文章摘要）可能影响性能。应考虑缓存过滤结果，或对确定无需HTML的内容使用更简单的 wp_strip_all_tags()。

忽略上下文特定转义。即使使用了 wp_kses_post()，输出到不同HTML位置仍需注意。例如，将过滤后的内容放入HTML属性时，应额外使用 esc_attr() 包裹，因为属性值有特殊的编码要求。

最佳实践

性能优化策略

对于重复输出的相同内容（如网站公告、页脚文本），应将过滤结果存储在变量或 transient 中，避免每次页面加载都重新解析。特别在自定义查询循环中，可在循环外预处理或使用对象缓存。

<?php
// 缓存 wp_kses_post 处理结果示例
function get_cached_announcement() {
    $cached = get_transient( 'site_announcement_html' );
    if ( false === $cached ) {
        $raw = get_option( 'site_announcement' );
        $cached = wp_kses_post( $raw );
        set_transient( 'site_announcement_html', $cached, HOUR_IN_SECONDS );
    }
    return $cached;
}
?>

代码组织与可维护性

在团队开发中，明确界定哪些数据源需要 wp_kses_post 处理。建议在主题或插件的公共函数文件中创建包装函数，统一处理逻辑并添加自定义允许的标签，确保全站过滤规则一致。

<?php
// 统一的自定义内容过滤函数
function mytheme_allowed_html_content( $content ) {
    // 获取默认的post规则集
    $allowed = wp_kses_allowed_html( 'post' );

    // 根据项目需求安全地添加额外允许的标签和属性
    $allowed['iframe'] = array(
        'src'             => true,
        'width'           => true,
        'height'          => true,
        'frameborder'     => true,
        'allowfullscreen' => true,
        // 注意：添加 iframe 等标签需评估具体风险
    );

    return wp_kses( $content, $allowed );
}
// 使用：echo mytheme_allowed_html_content( $raw_content );
?>

与现代开发模式结合

在开发 WordPress 区块时，区块的 save 函数返回的内容会自动通过 wp_kses_post() 过滤。但在自定义动态区块或 REST API 端点中返回HTML时，仍需手动应用过滤，确保前端安全渲染。对于通过 wp_localize_script() 传递到前端JavaScript的HTML内容，也应在PHP端预先过滤，因为前端转义更为复杂且易被绕过。