1. 问题现象与背景
在开发Web应用时，我们经常需要将动态生成或从数据库中获取的富文本内容（例如Markdown转换后的HTML）展示在页面上。然而，当这些包含HTML标签的内容被传递到Django模板并直接渲染时，我们可能会遇到一个常见的问题：HTML标签（如
、
、）并没有被浏览器解析和渲染，而是作为纯文本直接显示在页面上。
例如，当预期显示以下渲染效果时：
CSS === CSS is a language that can be used to add style to an [HTML](/wiki/HTML) page.
实际页面却可能直接显示其原始的HTML字符串：
CSS
CSS is a language that can be used to add style to an HTML page.
立即学习“前端免费学习笔记（深入）”；
这种现象的根本原因在于Django模板系统为了安全考虑，默认会对所有通过{{ variable }}语法输出的变量内容进行HTML转义。这意味着所有的、'、"和&字符都会被转换为对应的HTML实体（例如
考虑以下典型的Django视图和模板代码结构，它尝试将Markdown内容转换为HTML并显示：
views.py 片段：
import markdown
from . import util
from django.shortcuts import render
def entry(request, name):
entry_content_md = util.get_entry(name) # 获取Markdown格式内容
if entry_content_md is not None:
# 将Markdown转换为HTML
converted_html = markdown.markdown(entry_content_md)
context = {
'entry': converted_html, # 将HTML内容传递给模板
'name': name
}
return render(request, 'encyclopedia/entry.html', context)
else:
return render(request, "encyclopedia/404.html")
# util.py 中的辅助函数，用于读取Markdown文件内容
# def get_entry(title):
# try:
# f = default_storage.open(f"entries/{title}.md")
# return f.read().decode("utf-8")
# except FileNotFoundError:
# return Noneentry.html 片段：
{% block body %}
{% endblock %}在上述代码中，views.py 成功将Markdown转换为HTML，并将HTML字符串赋值给了模板上下文中的entry变量。然而，在entry.html中，{{ entry }}的默认行为导致了HTML标签被转义，最终显示为文本。
2. Django的自动转义机制及其安全性
Django的自动HTML转义是一项至关重要的安全特性，旨在保护Web应用免受XSS攻击。XSS攻击允许攻击者在受害者的浏览器中执行恶意脚本，窃取用户数据、劫持会话或篡改页面内容。通过默认转义所有输出，Django极大地降低了这类风险。
然而，当我们的意图是渲染合法的、预期的HTML内容时，这种默认行为就显得“过于安全”了。在这种情况下，我们需要一种方式来明确告诉Django：“这段内容是安全的HTML，请不要转义它，直接渲染。”
3. 解决方案：使用|safe过滤器
Django提供了一个名为safe的模板过滤器，用于解决上述问题。当一个变量被|safe过滤器处理时，Django会将其标记为“安全”的HTML，从而跳过对其内容的自动HTML转义过程，直接将其作为原始HTML输出到页面上。
要应用safe过滤器，只需在模板变量后加上|safe：
修改后的 entry.html 片段：
{% block body %}
{% endblock %}通过这一简单的改动，当entry变量包含由markdown.markdown()函数生成的HTML内容时，这些HTML标签将不再被转义，而是被浏览器正确解析和渲染，从而达到预期的显示效果。
4. 注意事项与最佳实践
尽管|safe过滤器能够解决HTML内容显示问题，但它的使用必须极其谨慎，因为它会绕过Django的安全防护机制。不当使用|safe是引入XSS漏洞的常见原因。
-
仅对信任的HTML内容使用|safe： 只有当你确信变量中包含的HTML内容是完全安全、无害的，才能使用|safe。这意味着这些HTML内容必须来自可靠的、受控的来源，例如：
- 由你自己的代码生成，且你已确保其中不包含任何恶意脚本。
- 从数据库中读取，且在存储前已经过严格的净化处理。
- 通过安全的第三方库（如Markdown解析器）生成，并且你信任该库的输出。
绝不直接对用户输入使用|safe： 如果你的网站允许用户提交包含HTML标签的内容（例如评论、论坛帖子），并且你直接将这些未经处理的用户输入与|safe一起使用，那么你的网站就极易受到XSS攻击。恶意用户可以提交包含
-
内容净化（Sanitization）： 如果你需要显示用户提交的、可能包含HTML的内容，强烈建议在将其存储到数据库或在模板中使用|safe之前，对其进行严格的净化处理。内容净化是指移除或转义所有潜在的恶意HTML标签和属性，只保留安全的HTML子集。常用的Python库如Bleach可以帮助你完成这项工作。
示例：使用Bleach净化用户输入
import bleach def process_user_content(raw_content): # 允许的HTML标签和属性 allowed_tags = ['p', 'a', 'strong', 'em', 'ul', 'ol', 'li', 'h1', 'h2'] allowed_attrs = {'a': ['href', 'title']} # 清理内容，移除不允许的标签和属性 cleaned_html = bleach.clean( raw_content, tags=allowed_tags, attributes=allowed_attrs, strip=True # 移除不允许的标签内容 ) return cleaned_html # 在视图中： # user_input_html = request.POST.get('description') # safe_html_for_db = process_user_content(user_input_html) # context = {'user_generated_content': safe_html_for_db} # return render(request, 'my_template.html', context) # 在模板中： {{ user_generated_content | safe }}
5. 总结
|safe过滤器是Django模板系统中一个强大且必要的工具，它允许开发者在需要时绕过默认的HTML转义机制，直接渲染HTML内容。然而，它的使用伴随着重要的安全责任。开发者必须始终牢记，只有当内容来源可靠且经过验证为安全时，才应使用|safe。对于任何可能包含用户输入或其他不可信来源的HTML内容，务必进行严格的净化处理，以确保应用程序的安全性，防止潜在的XSS攻击。正确理解和应用|safe过滤器，是构建健壮和安全的Django应用的关键一环。
