`escape` 和 `escapejs` 过滤器在 AnQiCMS 中各自适用于哪些 HTML/JS 转义场景？

在 AnQiCMS 的模板开发中，为了确保网站的安全性和内容的正确显示，理解并恰当地使用转义过滤器是十分重要的。系统采用类似 Django 的模板引擎语法，这意味着它在处理变量输出时，默认会采取一些安全措施。今天，我们就来聊聊 escape 和 escapejs 这两个过滤器，看看它们各自在哪些场景下能派上用场。

escape 过滤器：当你想显示原始 HTML/XML 特殊字符时

escape 过滤器的主要作用是将字符串中的特定 HTML/XML 特殊字符转换为它们对应的 HTML 实体。它会转义五个核心字符：< 变为 <，> 变为 >，& 变为 &，" 变为 "，以及 ' 变为 '。

AnQiCMS 的模板系统非常注重安全性，它默认会自动对所有从模板变量输出的内容进行 HTML 转义。这意味着当你直接使用 {{ variable }} 输出一个变量时，即使 variable 中包含了 <script> 标签，输出到页面上也会变成 <script>，从而有效防止了跨站脚本（XSS）攻击。

那么，既然默认就转义了，我们什么时候还需要手动使用 escape 过滤器呢？

1. 当你需要显示原始的 HTML/XML 代码文本时： 有时，你的网站可能需要展示一段代码示例，而这段代码本身就是 HTML 或 XML 格式。如果你直接输出，它会被浏览器解析并渲染。为了让用户看到这段代码的 文本形式 而不是渲染效果，你可能需要先使用 |safe 过滤器明确告诉系统这段内容是 “安全” 的（即你信任其内容不会导致 XSS），然后再次使用 |escape 将其转义为 HTML 实体，这样浏览器就会将其显示为文本。 例如，你有一个变量 myHtmlCode 值为 "<p>这是一个段落。</p>"：

   <!-- 这会渲染出一个段落，因为|safe阻止了默认转义 -->
   <div>{{ myHtmlCode|safe }}</div>
   
   
   <!-- 这会显示原始的HTML文本，如 <p>这是一个段落。</p> -->
   <div>{{ myHtmlCode|safe|escape }}</div>
   

   请注意，先使用 |safe 是因为你明确知道 myHtmlCode 里的 HTML 是你希望输出的，但又想将其作为文本显示，因此需要先绕过默认转义。

2. 显式地进行二次转义（通常不推荐）： 正如前面提到的，AnQiCMS 默认已经自动转义。如果你在 {{ variable }} 这样的输出上再次添加 |escape，就会导致内容被转义两次。这通常会导致页面显示不正确，例如 <p> 可能会变成 <p>，这不是我们希望看到的。所以，在大多数情况下，请避免不必要的 |escape 使用。

此外，AnQiCMS 也提供了 autoescape 标签，它允许你在模板的特定区域内控制自动转义的行为。

• {% autoescape off %}：在这个标签块内的所有变量输出将不会被自动转义。这在使用第三方库或特殊组件需要原始 HTML 输出时非常有用，但务必确保你输出的内容是绝对安全的，否则会引入 XSS 风险。
• {% autoescape on %}：显式地开启自动转义，这在某些特殊场景下可能有用，例如当某个变量被错误地标记为 safe 时，你可以强制对其进行转义。

{# 默认行为，变量会被自动转义 #}
<p>默认转义: {{ dangerous_html }}</p>

{# 关闭自动转义，但务必确保 dangerous_html 是安全的HTML #}
{% autoescape off %}
    <p>关闭转义: {{ dangerous_html }}</p>
{% endautoescape %}

escapejs 过滤器：当你在 JavaScript 中安全地插入数据时

escapejs 过滤器则是一个专门为 JavaScript 上下文设计的转义工具。它的任务是将字符串中的特殊字符（除了字母、数字、空格和斜杠 / 之外）转换为 JavaScript 字符串字面量可以安全识别的 \uXXXX 形式的 Unicode 转义序列。

为什么我们需要一个专门针对 JavaScript 的转义过滤器呢？ 想象一下，如果你想将一个 AnQiCMS 模板变量的值赋给一个 JavaScript 变量：

<script>
    var userName = "{{ user.name }}";
</script>

如果 user.name 的值是 '; alert('XSS'); //，那么最终渲染出的 HTML 会变成：

<script>
    var userName = ""; alert('XSS'); //";
</script>

这会导致一个严重的 JavaScript 注入漏洞，攻击者可以在你的网站上执行任意 JavaScript 代码。

escapejs 过滤器就是为了解决这类问题而生。它会确保所有可能破坏 JavaScript 字符串边界或引入恶意代码的字符都被安全地编码。

使用场景：将服务器端数据嵌入 <script> 标签内的 JavaScript 变量时。 只要你在 <script> 标签内部将 AnQiCMS 变量输出到 JavaScript 字符串、数组或对象中，就必须使用 escapejs 过滤器。

<script>
    var userName = '{{ user.name|escapejs }}';
    var userEmail = "{{ user.email|escapejs }}";
    var message = `欢迎，{{ message_from_backend|escapejs }}`; // 模板字符串中同样适用
</script>

这会将类似 '; alert('XSS'); // 的内容转义为 '\u0027; alert(\u0027XSS\u0027); \/\/，确保它在 JavaScript 代码中仍然是一个安全的字符串字面量，而不会被解析为可执行的代码。

核心安全原则：区分内容与代码的界限

在 AnQiCMS 模板开发中，记住以下几个核心原则，可以帮助你有效应对内容转义和安全问题：

1. 默认是安全的：AnQiCMS 模板引擎默认会对所有输出进行 HTML 转义。这意味着绝大部分时候，你不需要担心 XSS 风险，也不需要手动添加 |escape。
2. |safe 仅用于信任的 HTML 内容：只有当你确定某个变量包含的 HTML 内容是完全安全、且你希望浏览器能够正常解析和渲染它们时，才使用 |safe 过滤器。例如，从后台富文本编辑器中存储的文章内容，通常会带有 HTML 格式，此时使用 |safe 可以让这些内容正确显示。但请务必确保这些内容的来源是可信的。
3. |escapejs 始终用于 JavaScript 上下文：只要你在 <script> 标签内插入 AnQiCMS 变量（尤其是作为字符串字面量的一部分），请务必使用 |escapejs 过滤器。这是防止 JavaScript 注入漏洞的关键一步。

通过理解和遵循这些原则，你就可以在 AnQiCMS 中构建出既美观又安全、同时能正确展示各种内容的高质量网站。

---

常见问题解答 (FAQ)

Q1: 为什么我的 {{ variable }} 内容中包含 HTML 标签，但页面上显示的是原始的 HTML 实体（如 <p>）而不是渲染后的效果？ A1: AnQiCMS 模板引擎默认会对所有从变量输出的内容进行 HTML 转义，以防止跨站脚本（XSS）攻击。如果你确定这些 HTML 内容是安全的，并且希望它们被浏览器解析并渲染，你需要使用 |safe 过滤器，例如 {{ variable|safe }}。请务必谨慎使用 `