11ty项目中模板路径引用问题的解决方案

在11ty静态网站生成器项目中，开发者经常会遇到模板继承时的路径引用问题。本文将通过一个典型错误案例，详细分析问题原因并提供解决方案，帮助开发者正确配置模板路径。

问题现象

当开发者尝试在11ty项目中使用Nunjucks模板继承功能时，可能会遇到类似以下错误：

Error: template not found: /_layouts/base.njk

这个错误通常发生在模板文件中使用了类似下面的继承语句：

{% extends "/_layouts/base.njk" %}

问题根源分析

出现这个问题的根本原因在于11ty对模板路径的解析方式。11ty默认会从项目根目录开始查找模板文件，而不是从配置中指定的输入目录(src)开始。

在示例中，开发者虽然正确配置了输入目录：

dir: {
  input: "src",
  output: "_site",
  includes: "_includes",
  layouts: "_layouts",
  data: "_data",
}

但在模板继承语句中使用了绝对路径"/_layouts/base.njk"，这会导致11ty直接从文件系统根目录开始查找，而不是从项目目录开始。

解决方案

正确的引用方式应该是使用相对路径，有以下两种可行方案：

1. 使用相对于项目根目录的路径：

{% extends "./_layouts/base.njk" %}

2. 直接使用配置中定义的layouts目录名称：

{% extends "_layouts/base.njk" %}

最佳实践建议

1. 保持一致性：在整个项目中统一使用一种路径引用方式，推荐使用相对于项目根目录的路径。

2. 理解11ty的目录解析机制：11ty会按照以下顺序查找模板文件：

   • 首先检查是否有匹配的绝对路径
   • 然后检查相对于当前文件的路径
   • 最后检查配置中定义的layouts目录

3. 开发环境验证：在开发过程中，可以使用11ty的调试模式(DEBUG=Eleventy* eleventy)来查看模板解析的详细过程，帮助定位路径问题。

4. 跨平台考虑：使用正斜杠(/)作为路径分隔符，确保在Windows和Unix-like系统上都能正常工作。

通过理解11ty的模板解析机制并正确使用相对路径，开发者可以避免这类常见的模板继承问题，提高开发效率。