如何在模板中安全地显示HTML或JS代码而不被转义？
在安企CMS的模板开发和内容运营中，有时我们需要在页面上直接展示HTML代码或运行JavaScript脚本，而不是让它们被浏览器解析为纯文本。这通常发生在需要嵌入第三方统计代码、广告脚本，或者在文章内容中展示代码示例等场景。然而，安企CMS出于安全考虑，默认会对输出到模板中的内容进行HTML转义，以防止跨站脚本（XSS）等安全漏洞。
要实现在模板中安全地显示HTML或JS代码而不被转义，我们需要了解安企CMS提供的几个关键机制。
理解安企CMS的默认安全机制
首先，了解安企CMS的默认行为至关重要。作为一款企业级内容管理系统，安企CMS在设计之初就高度重视安全性。当您在后台输入任何可能包含HTML标签或JavaScript代码的内容并试图在前端模板中直接输出时，系统会默认进行HTML实体转义。这意味着 <script> 标签会被转换为 <script>，<p> 标签会变成 <p> 等，从而避免了恶意代码的执行。这种机制虽然在某些情况下看起来不方便，却是防止网站遭受XSS攻击的有效防线。
解除转义：safe 过滤器是关键
当您确定需要输出的内容是安全可靠的，并且希望它能够被浏览器正常解析为HTML元素或执行JavaScript代码时，可以使用安企CMS模板引擎提供的 safe 过滤器。safe 过滤器会告诉模板引擎，它所处理的内容已经被开发者明确标记为“安全”，无需进行HTML转义，可以直接输出。
使用方法：
您只需在需要解除转义的变量后面加上 |safe 即可。
例如，如果您有一个变量 customHtml 存储了自定义的HTML内容：
<div>
{{ customHtml|safe }}
</div>
或者，当您需要嵌入一段JavaScript统计代码：
<head>
<!-- 其他头部内容 -->
<script>
{{ statisticCode|safe }}
</script>
</head>
在 tag-tongji.md 文档中，也提到了类似用法：{{- pluginJsCode|safe }}。这表明对于统计代码等需要直接运行的JS片段，使用 safe 过滤器是标准的处理方式。
应用场景：
- 文章或页面内容中嵌入富文本： 如果您在后台的内容编辑器中输入了带有复杂HTML结构的富文本内容（例如，自定义布局的表格、包含特定样式的引用块），并且希望这些HTML能够被前端正确解析。通常情况下，像
archiveDetail标签中获取的Content字段，您会看到类似{{archiveContent|safe}}的用法，这确保了文章内容的富文本格式得以保留。 - 嵌入第三方脚本： 诸如Google Analytics、百度统计、在线客服系统等提供的JavaScript代码片段，需要直接插入到页面的
<head>或<body>中才能正常工作。 - 显示代码示例： 如果您想在网页上展示HTML、CSS或JavaScript代码片段，而不让它们被浏览器执行，但又希望它们以代码高亮等形式出现，通常会在服务器端预处理为HTML实体（例如使用Markdown转换器），然后通过
safe过滤器输出，以保持其格式。不过，如果仅仅是展示代码而不执行，更推荐的做法是将其放入<pre>和<code>标签，并确保内容本身已被正确转义（或在服务器端进行转义，再用safe输出）。
风险提示：
safe 过滤器虽然提供了灵活性，但也伴随着潜在的安全风险。一旦使用了 safe，就意味着您完全信任该变量中的内容。如果该变量来源于用户输入，或者未经严格过滤的外部数据，则可能导致XSS攻击。恶意用户可能通过注入JavaScript代码来窃取敏感信息、篡改页面内容或劫持用户会话。因此，请务必确保使用 safe 过滤器输出的内容来源可靠，并经过严格的过滤和验证。
局部控制转义：autoescape 标签
除了 safe 过滤器，安企CMS的模板引擎还提供了 autoescape 标签块，用于在特定区域内开启或关闭自动转义功能。
使用方法：
{% autoescape off %}
<!-- 在这个区块内的所有变量输出都不会被转义 -->
<div>{{ variableWithHtmlContent }}</div>
<script>{{ anotherScriptVariable }}</script>
{% endautoescape %}
{% autoescape on %}
<!-- 在这个区块内的所有变量输出都会强制被转义 -->
<div>{{ potentiallyMaliciousContent }}</div>
{% endautoescape %}
autoescape 标签适用于需要对一个较大代码块内的多个变量输出进行统一转义控制的场景，避免对每个变量都添加 |safe 或 |escape。
Markdown 内容的特殊处理
在 help-markdown.md 文档中提到，新版安企CMS支持Markdown编辑器，启用后，文档内容会“自动对内容进行 Markdown 转 html 操作”。这意味着如果您在后台使用Markdown语法撰写内容（包括Markdown格式的HTML或JS代码块），系统会自动将其转换为HTML并显示。
对于像 archiveDetail 标签获取的 Content 字段，它还支持一个 render 参数来手动控制Markdown渲染的行为：
{# 启用Markdown转HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
{# 不进行Markdown转HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>
这里需要注意的是，即使 render=true 进行了Markdown转HTML，最终的HTML输出仍然可能需要 |safe 过滤器才能在浏览器中正确显示和执行，以避免HTML标签被再次转义。
总结
在安企CMS模板中安全地显示HTML或JS代码，核心在于理解并恰当运用 safe 过滤器。它为您提供了绕过默认安全转义的灵活性，但同时也要求您对内容的来源和安全性负起责任。结合 autoescape 标签和对Markdown渲染的理解，您可以更精准地控制模板内容的显示行为，在确保网站安全的前提下，满足多样化的内容运营需求。
常见问题 (FAQ)
为什么我直接把HTML代码（例如
<p>这是一个段落</p>）放在模板里，它却显示成了文本而不是段落样式？ 这正是安企CMS默认安全机制在起作用。为了防止潜在的跨站脚本（XSS）攻击，系统会默认将所有输出的HTML标签进行转义，把<转换为<，>转换为>等。这样浏览器就不会将其解析为HTML元素，而是显示为纯文本。如果您确定这段HTML内容是安全的，并且希望它能够被浏览器正常解析，您需要在输出该内容的变量后面添加|safe过滤器。例如{{ myHtmlContent|safe }}。使用
safe过滤器后，是否意味着我嵌入的任何HTML或JS代码都绝对安全了？ 并非如此。safe过滤器只是告诉安企CMS模板引擎停止对该内容进行转义。它并不会对内容本身进行安全扫描或过滤。因此，使用safe意味着您作为开发者或运营者，需要对该内容的安全性负全部责任。如果内容来源于用户输入、外部API或其他不可信来源，您必须在内容进入数据库或被输出到模板之前，进行严格的过滤、验证和消毒处理，以防止恶意代码（如XSS攻击）的注入。简单来说，safe是一个“信任”标记，但信任的前提是您已确保了其安全性。我可以在安企CMS后台的内容编辑器里直接输入HTML代码或JS脚本，然后通过
safe过滤器让它在前台运行吗？ 可以，但需要区分情况并谨慎操作。- HTML代码： 如果您的内容编辑器支持富文本编辑（如WYSIWYG编辑器），通常编辑器本身就能处理和存储HTML。当您使用
archiveDetail等标签获取文章内容并加上|safe过滤器时，这些HTML标签就能被正常解析显示。 - JavaScript脚本： 虽然技术上可以在内容编辑器里输入
<script>标签并用|safe输出，但这不是推荐的做法。内容编辑器通常会移除或转义<script>标签以避免潜在风险。即使编辑器没有移除，将业务逻辑或统计脚本混入文章内容中，会使网站维护变得复杂，且难以进行版本控制。更佳实践是，将JavaScript脚本作为独立的资源文件或在模板文件中直接引用，并在必要时使用{{ myScriptCode|safe }}这样的变量输出。对于统计代码等，通常会直接由tag-tongji.md中提到的系统变量配合|safe输出。
- HTML代码： 如果您的内容编辑器支持富文本编辑（如WYSIWYG编辑器），通常编辑器本身就能处理和存储HTML。当您使用