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 内容会被自动转义，导致 <div> 显示为文本而非实际标签。

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 生态下最接近现代组件化开发体验的实践模式。