Eleventy 项目中 ESM 模板语法错误的调试技巧

问题背景

在 Eleventy 3.0.0 版本中，当使用 ESM (ECMAScript Modules) 格式的模板文件时，如果文件中存在语法错误，系统返回的错误信息往往不够明确，这给开发者调试带来了困难。

常见错误场景

以下是几种典型的错误情况及其表现：

1. 未完成的导出语句

export const

这种不完整的导出语句会导致"Unexpected end of input"错误。

2. 无效的模块内容

foo

直接写一个变量名而不遵循模块导出规范也会触发类似错误。

3. 新语法特性兼容问题

import foo from "./bar" with { type: "json" }

当使用较新的 JavaScript 语法特性时，可能会因为解析器不支持而报错。

错误信息的演变

在 Eleventy 3.0.0 中，错误信息仅显示：

Problem writing Eleventy templates:
Unexpected end of input (via SyntaxError)

而在 3.0.1-alpha.1 版本中，错误信息得到了改进，现在会显示：

Problem writing Eleventy templates:
1. There was a problem importing 'foo.11ty.js' via import(esm) (via EleventyImportError)
2. Unexpected end of input (via SyntaxError)

调试建议

1. 直接运行测试
   当遇到 Eleventy 报错时，可以尝试直接用 Node.js 运行问题文件：

   node problem-file.11ty.js
   

   这样通常能得到更直接的错误信息。

2. 检查语法兼容性
   确保使用的 JavaScript 语法特性在当前 Node.js 版本中得到支持。特别是注意：

   • 导入/导出语句的完整性
   • 新语法特性的支持情况

3. 版本升级
   考虑升级到 Eleventy 3.0.1 或更高版本，以获得更友好的错误提示。

技术原理

Eleventy 在底层使用 Acorn 解析器来处理 JavaScript 文件。当遇到语法错误时：

1. Node.js 的 ESM 加载器首先捕获错误
2. Eleventy 尝试包装并重新抛出错误
3. 在早期版本中，部分上下文信息在传递过程中丢失
4. 新版本改进了错误包装机制，保留了更多调试信息

最佳实践

1. 使用完整的模块导出语法
2. 在开发环境中，先单独测试模板文件
3. 保持 Eleventy 和 Node.js 版本更新
4. 对于复杂逻辑，考虑拆分为多个小模块

通过理解这些错误模式和调试技巧，开发者可以更高效地解决 Eleventy 项目中的 ESM 模板问题。