搭配Metalsmith-in-place使用Nunjucks include时出现渲染错误

我之前搭建Metalsmith静态站时也碰到过完全一样的坑！结合Nunjucks处理组件引用时，最容易踩的就是路径解析和插件配置顺序的问题，下面给你几个针对性的解决办法：

1. 给Nunjucks配置正确的搜索路径 #

metalsmith-in-place默认只会在当前页面的目录下查找Nunjucks文件，所以你需要明确告诉它组件和布局文件所在的目录。在插件配置里添加engineOptions.paths，把你的layouts和components目录都加进去：

const path = require('path');
const Metalsmith = require('metalsmith');
const inPlace = require('metalsmith-in-place');

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .use(inPlace({
    engine: 'nunjucks',
    engineOptions: {
      // 把需要搜索的目录都加到paths数组里
      paths: [
        path.join(__dirname, 'src/layouts'),
        path.join(__dirname, 'src/components')
      ]
    }
  }))
  .build((err) => {
    if (err) throw err;
    console.log('Build complete!');
  });

配置完成后，你在页面里的include就可以直接写文件名了：

{% include "test1.njk" %}

不用再写相对路径，Nunjucks会自动在你配置的目录里找文件。

2. 调整插件的使用逻辑（避免重复渲染冲突） #

如果你同时在用metalsmith-layouts和metalsmith-in-place，很容易出现重复处理Nunjucks语法的冲突。我的建议是统一用metalsmith-in-place处理所有Nunjucks逻辑——包括布局的extends和组件的include：

把layouts目录也加到paths里后，页面里的{% extends "layouts/base.njk" %}也能正常解析，这样就不需要再用metalsmith-layouts插件了，避免了两个插件之间的渲染冲突。

如果一定要保留metalsmith-layouts，那必须保证插件的执行顺序：先运行metalsmith-in-place处理页面内的include/宏，再运行metalsmith-layouts应用布局。不过这种方式容易出问题，更推荐上面的统一处理方案。

3. 排查基础路径和文件问题 #

有时候错误可能是低级失误导致的：

• 检查文件名和路径的大小写（Linux/macOS系统大小写敏感，Test1.njk和test1.njk是两个文件）
• 确认组件文件确实存在于你指定的components目录下，没有拼写错误
• 如果使用宏，确保引用方式正确（比如{% import "components/macros.njk" as macros %}后再调用{{ macros.myMacro() }}）

总结 #

90%的情况都是Nunjucks找不到你的组件文件，只要把搜索路径配置正确，再调整插件的使用方式，就能解决这个渲染错误。

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