Metalsmith中Nunjucks变量/宏语法未渲染直接原样输出如何解决？

Nunjucks语法标记直接输出为原文，说明对应文件没有被Nunjucks渲染器处理，常见原因如下：

• 插件执行顺序错误：如果Nunjucks渲染插件的调用顺序晚于Markdown转译、静态资源复制等插件，目标文件会被当作静态资源直接输出，不会执行模板解析逻辑
• 后缀匹配规则不包含目标文件：Metalsmith的Nunjucks插件默认只会解析配置中pattern字段指定后缀的文件，如果你用.html后缀写模板，但配置里只匹配.njk文件，对应文件就会被跳过
• 缺少YAML前置标记：部分Nunjucks集成插件要求模板文件顶部必须有YAML前置matter（哪怕是空的---\n---），才会被识别为需要渲染的模板
• Nunjucks实例配置错误：模板根目录配置错误、engineOptions参数异常都会导致渲染逻辑没有正常执行

按优先级逐一排查验证：

1. 调整插件执行顺序
   确保Nunjucks渲染插件的调用在所有内容后置处理插件之前，示例配置如下：

const Metalsmith = require('metalsmith')
const nunjucks = require('@metalsmith/layouts')
const markdown = require('@metalsmith/markdown')

Metalsmith(__dirname)
  // 先执行模板渲染
  .use(nunjucks({
    pattern: '**/*.{njk,html}', // 同时匹配njk和html后缀的模板文件
    engine: 'nunjucks',
    engineOptions: {
      trimBlocks: true,
      lstripBlocks: true
    }
  }))
  // 再执行Markdown转译、资源压缩等后续操作
  .use(markdown())
  .build((err) => {
    if (err) throw err
  })

2. 补充文件前置标记
   在出问题的模板文件顶部添加空的YAML前置标记：

---
---
<!-- 原有模板内容 -->

3. 验证宏导入逻辑
   确认宏导入的路径是相对于模板根目录的正确路径，导入语法没有拼写错误：

{% import "macros/common.njk" as someMacro %}
<!-- 调用时要带参数如果宏定义了参数 -->
{{ someMacro(params) }}

内容的提问来源于stack exchange，提问作者Umut。