本教程旨在解决Django模板中HTML内容被自动转义，导致HTML标签显示为纯文本而非实际渲染的问题。文章将解释Django的自动转义机制，并详细演示如何通过在模板中使用|safe过滤器，安全有效地将动态生成的HTML内容正确渲染到页面上，确保用户界面按预期显示。

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字符串：

<h1>CSS</h1> <p>CSS is a language that can be used to add style to an <a href="/wiki/HTML">HTML</a> page.</p>

这种现象的根本原因在于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 None

entry.html 片段：

{% block body %}
<div class="entry-container">
    <div class="left">
        {{ entry }} {# 这里直接输出了变量 #}
    </div>
    <div class="right">
        <a href="%7B%%20url%20'edit'%20%%7D" class="edit-btn">
            <button class="edit">EDIT</button>
        </a>
    </div>
</div>
{% 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 %}
<div class="entry-container">
    <div class="left">
        {{ entry | safe }} {# 关键改动：添加了 | safe 过滤器 #}
    </div>
    <div class="right">
        <a href="%7B%%20url%20'edit'%20%%7D" class="edit-btn">
            <button class="edit">EDIT</button>
        </a>
    </div>
</div>
{% endblock %}

通过这一简单的改动，当entry变量包含由markdown.markdown()函数生成的HTML内容时，这些HTML标签将不再被转义，而是被浏览器正确解析和渲染，从而达到预期的显示效果。

4. 注意事项与最佳实践

尽管|safe过滤器能够解决HTML内容显示问题，但它的使用必须极其谨慎，因为它会绕过Django的安全防护机制。不当使用|safe是引入XSS漏洞的常见原因。

• 仅对信任的HTML内容使用|safe： 只有当你确信变量中包含的HTML内容是完全安全、无害的，才能使用|safe。这意味着这些HTML内容必须来自可靠的、受控的来源，例如：

  • 由你自己的代码生成，且你已确保其中不包含任何恶意脚本。
  • 从数据库中读取，且在存储前已经过严格的净化处理。
  • 通过安全的第三方库（如Markdown解析器）生成，并且你信任该库的输出。

• 绝不直接对用户输入使用|safe： 如果你的网站允许用户提交包含HTML标签的内容（例如评论、论坛帖子），并且你直接将这些未经处理的用户输入与|safe一起使用，那么你的网站就极易受到XSS攻击。恶意用户可以提交包含<script>标签或其他攻击代码的内容，这些代码将在其他用户的浏览器中执行。</script>

• 内容净化（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应用的关键一环。

以上是Django模板中HTML标签显示为文本的解决方案：|safe过滤器详解的详细内容。更多信息请关注PHP中文网其他相关文章！