在使用 AnQiCMS 进行网站模板开发或内容展示时，有时会遇到需要直接在页面中输出包含 HTML 代码的内容，却发现这些代码被自动转义了，比如 <p> 标签变成了 &lt;p&gt;。这常常让初次接触的朋友感到困惑。实际上，这是 AnQiCMS 模板引擎为了网站安全而采取的默认措施。

理解 AnQiCMS 模板的默认安全机制

AnQiCMS 的模板引擎设计上借鉴了 Django 模板的语法，其核心理念之一就是安全性。默认情况下，模板引擎会将所有从变量输出的 HTML 特殊字符（如 <、>、&、"、'）自动转换为 HTML 实体。这个机制被称为“自动转义”，它能够有效防止跨站脚本攻击（XSS）等常见的安全漏洞。如果不对用户输入的内容进行处理就直接输出，恶意用户可能会在内容中插入 <script> 标签，从而执行恶意代码，窃取用户数据或破坏页面。

虽然这种默认行为增加了安全性，但当我们确实需要输出由富文本编辑器生成或从受信任来源获取的 HTML 内容时，就需要一种方式来告诉模板引擎：“这段内容是安全的，请不要转义它。”

使用 |safe 过滤器输出原始 HTML

当您明确知道要输出的内容是安全且包含有效 HTML 结构时，可以使用 |safe 过滤器来指示模板引擎跳过自动转义过程，直接输出原始内容。

这个过滤器的使用方法非常简单，只需在您要输出的变量后面加上 |safe 即可。例如，在 AnQiCMS 中，您经常会遇到需要输出文章内容 (archive.Content)、分类内容 (category.Content) 或单页面内容 (page.Content) 的场景，这些内容通常都是通过富文本编辑器录入，本身就包含了 HTML 标签。

您可以这样在模板中使用它：

{# 默认，内容会被转义 #}
<div>{{ archive.Content }}</div>

{# 使用 |safe 过滤器，内容将作为原始HTML输出 #}
<div>{{ archive.Content|safe }}</div>

通过添加 |safe，模板引擎就会将 archive.Content 中的 <p>、<img>、<strong> 等 HTML 标签按原样输出，而不是将其转换为 &lt;p&gt;、&lt;img&gt;、&lt;strong&gt; 等。同样的方法也适用于其他可能包含 HTML 的字段，例如：

  • 分类详情的描述：{{ category.Description|safe }}
  • 单页面内容：{{ page.Content|safe }}
  • 任何您在后台自定义并包含 HTML 标签的字段。

重要提示： 使用 |safe 过滤器时务必谨慎。只有当您完全信任内容的来源，并确保其中不含恶意脚本时才应使用。否则，可能会给网站带来安全风险。

灵活控制：autoescape 标签块

除了对单个变量使用 |safe 过滤器，AnQiCMS 也提供了 {% autoescape %} 标签来控制一个模板块内的自动转义行为。这对于管理较大段落或多个变量的输出非常有用。

您可以使用 {% autoescape off %} 来关闭一个区块的自动转义，并在该区块结束时用 {% autoescape on %} 或 {% endautoescape %} 重新开启。

例如，如果您有一个区域包含多段内容，您希望它们都以原始 HTML 形式输出：

{# 默认，这里的内容会被转义 #}
<p>这是被转义的普通文本。</p>

{% autoescape off %}
    {# 在这个区块内，所有变量输出将不会被自动转义 #}
    <h3>{{ trusted_title_html }}</h3>
    <div>{{ trusted_body_html }}</div>
    <p>这段内容也直接输出 HTML。</p>
{% endautoescape %}

{# 自动转义再次生效 #}
<p>这是恢复自动转义后的普通文本。</p>

这种方式适用于某个特定区域的 HTML 内容需要整体关闭或开启转义，而不想逐个变量添加 |safe 的场景。同样地，使用 autoescape off 标签时，也需要确保该区块内的所有内容都是完全受信任和安全的。

处理 Markdown 内容的输出

在 AnQiCMS 中，如果您的内容字段启用了 Markdown 编辑器，那么系统在输出时会先将 Markdown 语法渲染成 HTML 代码。此时，您可能依然需要确保这些渲染后的 HTML 能够正确显示。

对于启用了 Markdown 的内容字段，如 archive.Content，当您使用 archiveDetail 标签获取内容时，可以通过添加 render=true 参数来让系统先进行 Markdown 到 HTML 的转换。例如：

{# 获取并渲染Markdown内容为HTML #}
{% archiveDetail archiveContent with name="Content" render=true %}
    {# 即使内容经过了 render=true 处理，最终输出到页面时，依然建议结合 |safe 过滤器使用 #}
    <div>{{ archiveContent|safe }}</div>

这里的 render=true 告诉 AnQiCMS 引擎在输出前将 Markdown 格式转换为 HTML。之后，|safe 过滤器则确保这些转换后的 HTML 代码不会被模板引擎再次转义，从而在页面上正常显示。

**实践与安全考量

为了最大程度地保证网站安全，建议在内容输入阶段就进行严格把控。AnQiCMS 后台的富文本编辑器通常会过滤掉一些危险的 HTML 标签和属性，但对于自定义字段或其他不经过编辑器处理的内容，开发者应自行判断其安全性。

简而言之，|safe 过滤器是您输出原始 HTML 的利器，但它也是一把双刃剑，用之得当则内容丰富，用之不当则安全堪忧。通过灵活运用 |safe 过滤器和 {% autoescape %} 标签，您可以安全、有效地在 AnQiCMS 模板中输出包含 HTML 代码的内容。始终记住，在享受内容展示灵活性的同时，保障网站安全是首要任务。

常见问题 (FAQ)

Q1: 为什么 AnQiCMS 模板默认要转义 HTML 代码？ A1: AnQiCMS 模板引擎默认进行 HTML 代码转义是为了提高网站的安全性，特别是为了防止跨站脚本攻击（XSS）。XSS 是一种常见的网络安全漏洞，攻击者可能通过在内容中注入恶意 HTML 或 JavaScript 代码来窃取用户数据、篡改页面或执行其他恶意操作。自动转义机制将特殊字符转换为无害的 HTML 实体，从而中和了这些潜在威胁。

Q2: 我在后台富文本编辑器里输入的内容，为什么还是需要 |safe 才能在前端正确显示？ A2: 后台富文本编辑器在保存内容时虽然会过滤掉一些明确不安全的标签和属性，以确保存储的内容相对安全，但这与模板引擎的自动转义是两个独立的安全层。模板引擎在将任何变量输出到页面时，都会再次执行自动转义。因此，即使编辑器生成的是合法且无害的 HTML，为了确保这些 HTML 标签能在前端正常