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="%7B%7B%20slide.image%20%7D%7D" 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 生态下最接近现代组件化开发体验的实践模式。
