Nunjucks 嵌套模板包含与数据传递技巧

Nunjucks 虽不支持原生的 `{% include "xxx" with {...} %}` 语法，但通过自定义 `render` 过滤器可安全、灵活地实现类似 React 的组件化开发体验——精准传递纯净上下文、严格隔离作用域、支持多层递归嵌套，并兼顾路径解析与 XSS 防护；本文手把手教你注册过滤器、重构模板结构、规避常见陷阱（如宏不可用、异步加载限制），并给出已在 11ty 等生产环境验证的可靠实践，让 Nunjucks 模板真正拥有现代前端般的可维护性与可预测性。

Nunjucks 原生不支持 {% include "xxx" with {...} %} 语法，但可通过自定义 render 过滤器安全、递归地传递上下文数据，实现类似 React 的 props 下传效果。本文详解替代方案、代码实现及关键注意事项。

Nunjucks 原生不支持 `{% include "xxx" with {...} %}` 语法，但可通过自定义 `render` 过滤器安全、递归地传递上下文数据，实现类似 React 的 props 下传效果。本文详解替代方案、代码实现及关键注意事项。

在 Nunjucks 中模拟 React 的“组件化 + props 透传”能力，核心挑战在于其 include 标签不支持 with 子句（如 {% include "card.html" with {item: slide} %} 会直接报错 expected block end in include statement）。官方语法仅允许 {% include "template.njk" %}，且被包含模板默认继承父模板全部上下文——这既不安全也不灵活，尤其在嵌套层级较深、需隔离/精简传入数据时极易引发变量污染或命名冲突。

✅ 正确解法：注册自定义 render 过滤器
该方案通过 env.render() 手动渲染子模板，并显式传入纯净上下文对象，完全绕过 include 的语法限制，同时保留作用域隔离与类型可控性。

1. 在 Node.js 环境中注册 render 过滤器（推荐在初始化 Nunjucks 时配置）：

const nunjucks = require('nunjucks');

const env = nunjucks.configure({
  autoescape: true,
  // 其他配置项...
});

// 注册安全的 render 过滤器
env.addFilter('render', (templatePath, context = {}) => {
  try {
    // 使用 env.render（非 renderString）以支持相对路径和 loader 机制
    return env.filters.safe(env.render(templatePath, context));
  } catch (err) {
    console.error(`Failed to render template "${templatePath}":`, err);
    throw err;
  }
});

⚠️ 注意：务必使用 env.filters.safe() 包裹结果，否则 HTML 内容会被自动转义，导致

显示为文本而非实际标签。

2. 改写原始模板结构（保持语义清晰）：

Page 模板（page.html）：

{% set slides = [
  { "alt": "Tokenization Visualization", "title": "Tokenization", "description": "The LLM starts by breaking down the input text...", "image": "/img/ai/carousels/how-llm-works/tokenization.png" },
  { "alt": "Embedding Visualization", "title": "Embedding", "description": "Next, each token is converted into a numerical representation...", "image": "/img/ai/carousels/how-llm-works/embedding.png" },
  // ...其余项
] %}

{{ 'partials/image-cards/image-cards.html' | render({ slides: slides }) }}

Image-cards 模板（partials/image-cards/image-cards.html）：

<div class="image-cards flex flex-wrap justify-between py-6 ff-inter">
  {% for slide in slides %}
    {{ 'partials/image-cards/image-card.html' | render({
        slide: slide,
        index: loop.index
      }) }}
  {% endfor %}
</div>

Image-card 模板（partials/image-cards/image-card.html）：

<div id="item{{ index }}" class="card card-compact w-full md:w-[45%] shrink-0 grow-0s mt-10">
  <figure class="card-figure !mt-0 !mb-0">
    <img src="{{ slide.image }}" alt="{{ slide.alt }}" class="w-full" />
  </figure>
  <div class="card-body !px-0 text-primary-content whitespace-normal">
    <div class="font-semibold mb-0">{{ slide.title }}</div>
    <p>{{ slide.description }}</p>
  </div>
</div>

✅ 优势总结：

• ✅ 作用域隔离：每个 render 调用只接收明确传入的 context，无隐式变量泄漏；
• ✅ 类型安全：IDE 和 Lint 工具可更好校验 slide.title 等字段是否存在；
• ✅ 可递归嵌套：支持多层 render 调用（如 image-card 再 render 一个 caption.html）；
• ✅ 路径友好：基于 Nunjucks 的 loader 机制，支持相对路径与模板继承。

⚠️ 注意事项：

• ❌ render 过滤器无法调用宏（macro） —— 宏必须在当前模板作用域内定义或 import；若需复用逻辑，建议将宏提取为独立模板并用 render 调用；
• ⚠️ 异步模板加载（如从数据库读取）需扩展 render 为异步过滤器（addAsyncFilter），并配合 async/await 使用；
• ? 生产环境务必开启 autoescape: true 并始终用 safe() 包裹 render 结果，防止 XSS。

此方案已在多个大型静态站点生成器（如 11ty + Nunjucks）中验证稳定，是目前 Nunjucks 生态下最接近现代组件化开发体验的实践模式。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~