Mozilla Bleach 库：HTML 文本安全净化指南-优快云博客

Mozilla Bleach 库：HTML 文本安全净化指南

bleach Bleach is an allowed-list-based HTML sanitizing library that escapes or strips markup and attributes 项目地址: https://gitcode.com/gh_mirrors/bl/bleach

什么是 Bleach？

Mozilla Bleach 是一个专门用于 HTML 文本片段安全净化的 Python 库。它能解析 HTML5 内容，对标签、属性和其他元素进行安全处理，确保输出的 HTML 片段可以安全地在网页中使用。

核心功能

Bleach 提供两种主要净化方式：

bleach.clean() 函数 - 简单易用的快捷方法
bleach.sanitizer.Cleaner 类 - 提供更多配置选项

安全警告

重要提示：bleach.clean() 仅适用于 HTML 上下文，不能用于以下场景：

HTML 属性值
CSS 样式
JavaScript 代码
各种模板引擎（Mustache、Handlebars、Angular 等）
JSON、XHTML、SVG 等其他上下文

正确示例：

<p>{{ bleach.clean(user_bio) }}</p>

错误示例：

<body data-bio="{{ bleach.clean(user_bio) }}">

主要净化选项

1. 允许的标签 (tags)

通过 tags 参数指定允许保留的 HTML 标签列表，不在列表中的标签将被转义或删除。

import bleach
bleach.clean('<b><i>示例</i></b>', tags={'b'})
# 输出: '<b>&lt;i&gt;示例&lt;/i&gt;</b>'

默认允许的标签列表存储在 bleach.sanitizer.ALLOWED_TAGS 中。

2. 允许的属性 (attributes)

attributes 参数控制允许保留的属性，支持多种配置方式：

列表形式

允许所有标签使用指定的属性列表：

bleach.clean(
    '<p class="foo" style="color:red;">内容</p>',
    tags={'p'},
    attributes=['class']
)
# 输出: '<p class="foo">内容</p>'

字典形式

精细控制不同标签允许的属性：

attrs = {
    '*': ['class'],  # 所有标签允许class属性
    'a': ['href', 'rel'],
    'img': ['alt']
}

回调函数

通过函数动态决定是否保留属性：

def allow_h(tag, name, value):
    return name[0] == 'h'  # 只保留h开头的属性

bleach.clean(
    '<a href="..." title="链接">链接</a>',
    tags={'a'},
    attributes=allow_h
)
# 输出: '<a href="...">链接</a>'

3. 允许的协议 (protocols)

控制允许的 URL 协议（如 href、src 等属性）：

bleach.clean(
    '<a href="smb://example">链接</a>',
    protocols={'http', 'https', 'smb'}
)

4. 其他净化选项

strip=True：删除而非转义不允许的标签
strip_comments=False：保留 HTML 注释（默认删除）

CSS 样式净化

Bleach 还能净化 style 属性中的 CSS 内容，需要额外安装依赖：

pip install 'bleach[css]'

使用示例：

from bleach.css_sanitizer import CSSSanitizer

css_sanitizer = CSSSanitizer(allowed_css_properties=["color", "font-weight"])
bleach.clean(
    '<p style="font-weight: bold;">文本</p>',
    tags={'p'},
    attributes={'*': ['style']},
    css_sanitizer=css_sanitizer
)

高级用法：Cleaner 类

对于大量文本处理或需要更精细控制时，建议直接使用 Cleaner 类：

from bleach.sanitizer import Cleaner

cleaner = Cleaner(
    tags={'b', 'i'},
    attributes={'b': ['class']},
    strip=True
)
cleaner.clean('<b class="bold"><i>斜体</i></b>')

过滤器机制

Bleach 基于 html5lib 的过滤器机制实现，允许添加自定义过滤器对内容进行额外处理：

class MooFilter(Filter):
    def __iter__(self):
        for token in super().__iter__():
            if token['type'] in ['StartTag', 'EmptyTag']:
                token['data'] = {k: 'moo' for k in token['data']}
            yield token

cleaner = Cleaner(filters=[MooFilter])