在网站运营中，我们经常需要展示包含丰富排版和媒体内容的信息，例如精心编辑的文章详情、产品介绍或自定义页面。这些内容往往包含 HTML 标签，如图片标签 <img>、链接标签 <a>、段落标签 <p> 等。然而，如果你直接将这些内容输出到网页上，可能会发现它们并没有按照预期渲染，而是以文本形式原样显示了 HTML 标签，大大影响了用户体验和页面的美观度。
这并非 AnQiCMS 的问题，而是一种默认的安全机制。为了保障网站的安全，有效防范跨站脚本攻击（XSS）等潜在风险，AnQiCMS 的模板引擎默认会对所有通过 {{变量}} 方式输出的内容进行 HTML 转义。这意味着，像 <script> 标签会被转换为 <script>，从而避免浏览器将其识别为可执行代码。这种机制在处理用户提交的不可信内容时尤其重要。
理解 AnQiCMS 模板机制与默认转义
AnQiCMS 采用类似 Django 模板引擎的语法，变量通过双花括号 {{变量}} 输出，而控制逻辑则通过单花括号和百分号 {% 标签 %} 定义。当你在模板中直接输出一个包含 HTML 的变量时，例如 {{archive.Content}}，系统会将其中的 <、> 等特殊字符转换成对应的 HTML 实体，以此来阻止浏览器执行任何嵌入其中的恶意代码。
这种默认转义行为虽然提升了安全性，但对于我们希望正常渲染的富文本内容，就需要明确告知模板引擎——这段内容是安全的，可以放心渲染。
核心解决方案：safe 过滤器
当系统判断到某个输出内容是经过管理员审核、确认是安全的，并且确实需要以 HTML 形式渲染时，我们可以使用 AnQiCMS 模板引擎提供的 |safe 过滤器。
|safe 过滤器的作用非常直接：它明确告知模板引擎，此内容是“安全”的，不需要进行 HTML 转义，可以直接作为 HTML 渲染到页面上。
它的使用方式非常简单，只需要在需要输出 HTML 的变量后面加上 |safe 即可：
{{ 你的变量 | safe }}
例如：
在文档详情页面，我们通常需要显示 archive 对象的 Content 字段，这个字段包含了文章的正文内容，其中可能含有图片、视频等 HTML 元素。为了让这些内容正确显示，我们会这样使用：
<div>
{%- archiveDetail articleContent with name="Content" %}
{{articleContent|safe}}
</div>
在这里，archiveDetail 标签获取了文章的 Content 内容，并将其赋值给 articleContent 变量。随后，{{articleContent|safe}} 则确保了这些内容能够被浏览器正确解析为 HTML。
处理富文本内容：常见场景与注意事项
|safe 过滤器在多个场景下都至关重要：
通用内容字段（如
Content）： 在 AnQiCMS 中，像文章（archiveDetail）、单页面（pageDetail）、分类详情（categoryDetail）或标签详情（tagDetail）等的核心内容区域（通常是Content字段），往往会包含通过富文本编辑器编辑的 HTML 结构。这些内容通常由管理员在后台创建和管理，被认为是可信的。因此，在这些场景下，应用|safe过滤器是确保内容正确渲染的关键一步。{# 示例：单页面内容 #} <div> {% pageDetail pageContent with name="Content" %} {{pageContent|safe}} </div>Markdown 内容的特别处理： AnQiCMS 支持 Markdown 编辑器，这意味着一些内容可能以 Markdown 格式存储。如果你在后台启用了 Markdown 编辑器，并希望将 Markdown 内容渲染为 HTML 并显示，那么处理过程会稍微复杂一些，因为 Markdown 内容首先需要被转换成 HTML，然后才能被标记为“安全”。
此时，你需要同时使用
render参数和|safe过滤器：{# 示例：Markdown 内容渲染为 HTML #} <div> {% archiveDetail archiveContent with name="Content" render=true %} {{archiveContent|safe}} </div>这里的
render=true参数告诉模板引擎将 Markdown 格式的Content字段先转换为 HTML，然后|safe过滤器再确保转换后的 HTML 能够不被转义地输出到页面上。自定义字段中的 HTML： 有时，我们可能会在内容模型中创建自定义字段来存储特定的 HTML 片段，例如产品特色描述、特殊的营销文本或需要特别样式控制的文本块。如果这些自定义字段的内容也包含了 HTML 标签，同样需要应用
|safe过滤器才能正确显示。{# 示例：自定义字段 'product_features' 包含 HTML #} <div> <h3>产品特色：</h3> {% archiveDetail productFeatures with name="product_features" %} {{productFeatures|safe}} </div>
安全与风险：为什么要小心使用 safe？
虽然 |safe 过滤器能够解决 HTML 内容被转义的问题，但它也带来了潜在的安全风险。其核心在于，一旦你使用了 |safe，你就明确告诉系统“我信任这段内容，它没有恶意代码”。
如果这段“安全”内容实际上被攻击者注入了恶意脚本（例如 <script>alert('您被黑了');</script>），并且你使用了 |safe 输出，那么这些恶意脚本就会在访问你网站的用户的浏览器中执行。这就是所谓的 跨站脚本攻击（XSS）。攻击者可能通过注入恶意脚本来窃取用户信息、篡改页面内容，甚至劫持用户会话。
因此，在使用 |safe 过滤器时，必须遵循以下原则：
- 只用于你完全信任的内容来源： 例如，由网站管理员在后台通过富文本编辑器创建的内容，通常被认为是可信的，因为只有有权限的管理员才能编辑。
- 绝不能直接用于用户提交的、未经严格消毒（Sanitization）的内容： 任何可能由最终用户输入的文本字段，即使看上去只是普通评论或留言，都绝不能直接使用
|safe输出。这些内容必须经过后端服务器的严格过滤和消毒，移除所有潜在的恶意标签和属性，才能考虑在安全的前提下进行 HTML 渲染（如果确有此需求）。AnQiCMS 提供了防采集干扰码、内容安全管理、敏感词过滤等功能，可以辅助提高内容安全性，但在前端输出用户生成内容时仍需谨慎。
高级控制：autoescape 标签
除了针对单个变量使用 |safe 过滤器外，AnQiCMS 也提供了 autoescape 标签来控制一个模板块内的自动转义行为。它允许你在一个特定的代码块中临时关闭或开启默认的 HTML 转义。
{% autoescape off %}： 在此标签到{% endautoescape %}之间，所有{{变量}}的输出都不会进行 HTML 转义，效果相当于每个变量都自动带了|safe过滤器。{% autoescape on %}： 这是默认行为，所有{{变量}}的输出都会进行 HTML 转义。
示例：
{% autoescape off %}
<p>这个段落里的 {{ untrusted_html_content }} 将不会被转义。</p>
{% endautoescape %}
{% autoescape on %}
<p>这个段落里的 {{ trusted_html_content }} 将会被转义。</p>
{% endautoescape %}
需要注意的是，|safe 过滤器会优先于 autoescape 标签。也就是说，即使在 autoescape on 的块中，对某个变量使用了 |safe，该变量依然不会被转义。反之，在 autoescape off 的块中，使用 |escape 过滤器可以强制进行转义。
总结
在 AnQiCMS 模板中安全地输出包含 HTML 标签的内容，关键在于恰当使用 |safe 过滤器或 autoescape 标签。这需要我们在实现预期显示效果的同时，时刻警惕安全风险。对于管理员维护的、可信的富文本内容，使用 |safe 是标准做法。而对于可能包含用户输入的内容，则必须采取额外的内容安全措施，避免直接使用 |safe，