企业官网建设流程全解析

• 前端
• 开发工具

本文以 buildawesome 仓库中的 prematureTemplateContent 测试夹具为起点，剖析"过早读取templateContent"这一经典错误的触发条件、错误类型、跨模板引擎的识别机制，以及 Eleventy 构建核心为解决该问题而设计的两阶段渲染 + 循环引用检测原理。读完本文，你将能在自己的模板与数据流中准确判断templateContent何时可用、何时不可用，并理解构建器内部对集合内容的填充时机。

一、问题的起点：一个一行的测试夹具

在 test/stubs/prematureTemplateContent/ 目录下，存放着一组专门用于验证"过早使用templateContent"行为的测试夹具。其中的 test.md 全文只有一行：

{{ sample.templateContent }}

这一行模板表达式本身并不能独立构成文档，但它在整个夹具组和测试体系中承担着精确的语义：在模板渲染尚未完成时，尝试读取另一个数据对象（sample）上的templateContent属性。与它配套的还有三个同目录夹具，覆盖了不同模板语言下的相同场景：

• test.liquid：{{ collections.all[0].templateContent }}—— 通过集合访问第一个模板的templateContent；
• test.njk：{{ sample.templateContent }}—— 与test.md相同，但走 Nunjucks 引擎；
• test.11ty.cjs：以 JavaScript 模板形式返回data.collections.all[0].templateContent。

四份夹具分别命中四种模板引擎（Liquid、Nunjucks、JavaScript、Markdown 经由 Liquid 处理），共同验证：无论哪种语言，只要在错误的阶段读取templateContent，构建器都必须抛出统一的、可识别的错误。

二、templateContent是什么，为什么"过早读取"是错误

在 buildawesome（Eleventy）的模板数据模型中，每个模板页面的数据对象上都有一个templateContent属性，语义上表示该模板在不套用布局的情况下渲染出的最终内容。它只应该在模板被实际渲染之后才可读；在渲染之前读取，拿到的必然是尚未产生的内容，因此被明确视为编程错误。

这一约束并非在模板引擎层实现，而是在数据对象的属性定义层实现。核心代码位于 src/Template.js 的augmentWithTemplateContentProperty方法中，它通过Object.defineProperties为页面对象注入三个非枚举或枚举属性：

• needsCheck（非枚举、可写）：一个内部标记，初始为true，表示"尚未确认内容已就绪"；
• _templateContent（非枚举、可写）：真正存储渲染结果的后备字段，初始为undefined；
• templateContent（枚举）：一个带 getter/setter 的访问器属性。setter在收到undefined时会把needsCheck置为false（表示该模板不产出内容），否则写入_templateContent；getter在needsCheck === true且_templateContent === undefined时直接抛出错误。

getter 的判定逻辑还区分了两种情况（src/Template.js）：

get() { if (this.needsCheck && this._templateContent === undefined) { if (this.template.isRenderable()) { throw new TemplateContentPrematureUseError( `Tried to use templateContent too early on ${this.inputPath}...` ); } else { throw new TemplateContentUnrenderedTemplateError( `Tried to use templateContent on unrendered template: ${this.inputPath}` ); } } return this._templateContent; }

也就是说：

• 模板可渲染但内容尚未渲染→ 抛出TemplateContentPrematureUseError，错误信息形如Tried to use templateContent too early on <inputPath>；
• 模板本身不可渲染（如纯静态文件）→ 抛出TemplateContentUnrenderedTemplateError，信息形如Tried to use templateContent on unrendered template: <inputPath>。

此外，同一段代码还定义了一个枚举的content别名（src/Template.js），其 getter 直接转发给templateContent，而 setter 则明确拒绝赋值并提示"请改用templateContent"。这解释了为什么在模板里写content同样可能触发过早读取错误。

三、错误类型与跨引擎识别机制

与上述两个错误并列的还有第三个错误类，全部继承自统一的 BaseError：

困难在于：这类错误在真实构建中往往不是"裸奔"抛出，而是被各模板引擎的运行时层层包装。为此，src/Errors/ErrorUtil.js 提供了isPrematureTemplateContentError(e)作为统一识别入口，依次检查四条路径：

1. 错误本身是TemplateContentPremureUseError实例；
2. 错误的cause链上是该错误实例（对应 JavaScript/Custom 引擎按 Node 惯例设置的原因链）；
3. 错误是 Liquid 引擎包装出的RenderError/UndefinedVariableError，且其originalError.originalError是该错误实例；
4. 错误信息字符串中包含TemplateContentPrematureUseError（对应 Nunjucks 引擎的文本化错误）。

这条识别逻辑是后续两阶段渲染得以实现的基础——构建器必须能跨引擎确认"这次渲染失败是因为内容过早使用，而不是其他致命错误"。

四、仓库测试如何验证这一行为

test/TemplateTest.js 中针对该夹具组编写了六条测试（第 1451–1561 行），构成了对这一行为最直接的验收证据：

• Nunjucks 直接访问：对test.njk调用getData()与getTemplates(data)后，同步读取mapEntries[0].templateContent，断言抛出的是 premature 错误（test/TemplateTest.js）；
• Nunjucks 渲染路径：用get templateContent() { throw new TemplateContentPrematureUseError(...) }模拟数据源，在renderPageEntry渲染过程中捕获异步错误并断言（test/TemplateTest.js）；
• Liquid 直接访问（test/TemplateTest.js）；
• 11ty.js 直接访问（test/TemplateTest.js）；
• Markdown 直接访问（test/TemplateTest.js）；
• Markdown 渲染路径（test/TemplateTest.js）。

所有断言统一使用ErrorUtil.isPrematureTemplateContentError(error) === true，这正是上一节识别机制的实战用例。可以推断，夹具组按引擎拆分（test.md走 Liquid 预处理、test.njk走 Nunjucks、test.11ty.cjs走 JavaScript）正是为了覆盖识别逻辑中的每一条分支路径。

五、底层原理：TemplateMap 的两阶段渲染与循环引用检测

为什么构建器能"容忍"一次 premature 错误并最终给出正确结果？答案在 src/TemplateMap.js 的cache()流程中，它把渲染过程组织成两阶段：

第一阶段（主渲染）：按用户配置的并发度（userConfig.getConcurrency()）分块并行执行，对每个pageEntry调用renderPageEntryWithoutLayout(pageEntry)，并把结果写入pageEntry.templateContent。源码注释明确写道：IMPORTANT: this is where template content is rendered（src/TemplateMap.js）。若该阶段捕获到 premature 错误，构建器并不会直接失败，而是：

• 把该map记入usedTemplateContentTooEarlyMap队列；
• 对相关pageEntry调用resetCaches({ render: true })清除渲染缓存（src/TemplateMap.js）。

第二阶段（重渲染）：遍历第一阶段的"问题队列"再次渲染。若这次成功，则内容就绪；若仍然抛出 premature 错误，则说明该模板是在集合中自引用自己的templateContent，属于必然死循环，于是抛出一个新的UsingCircularTemplateContentReferenceError，错误信息为：

... contains a circular reference (using collections) to its own templateContent.

（src/TemplateMap.js）

这一设计保证了：依赖其他模板内容的模板，只要不构成循环，就能在第二轮拿到正确内容；只有真正自引用的模板才会报错。

循环引用场景在 test/TemplateMapTest.js 中有专门验证：夹具 test/stubs/templateMapCollection/templateContent.md 内容为{{ collections.circle[0].templateContent }}，同时自己的 front matter 打了tags: circle标签——它在集合中引用自己，tm.cache()最终抛出UsingCircularTemplateContentReferenceError。

六、合法的使用场景：templateContent何时可用

弄清"何时不能用"之后，更重要的是掌握"何时能用"。从源码中可以梳理出三条确定性的可用时机：

1. 集合内容填充（populateCollectionsWithContent）。cache()完成后，src/TemplateMap.js 会把已渲染的_templateContent回填到集合条目上（仅当内容已定义时才赋值，且跳过配置文件中自定义的非数组集合）。因此，在渲染阶段通过collections.all[0].templateContent读取其他模板的内容是安全的——这正是test.liquid与test.11ty.cjs里表达式想要表达、但只有在正确阶段才会成功的用法。

2. 布局渲染（layout 的content变量）。src/TemplateLayout.js 在渲染布局时会读取pageEntry.templateContent，将其经cdata.wrap包裹后注入布局数据并执行渲染，最后取回结果。同时该代码特意不把布局后的内容写回pageEntry.templateContent（注释：collection items should not have layout markup），以保证集合中的templateContent始终是"不含布局标记"的原始渲染结果。

3. 计算数据第二轮（resolveRemainingComputedData）。src/Template.js 中该方法注释为Computed data consuming collections!，它是在渲染之后运行的第二轮计算数据阶段（由 src/TemplateMap.js 统一调度），从源码结构看，这是模板内依赖集合内容的eleventyComputed数据被解析的时机。

反过来说，绝对要避免的写法是：模板在自己的内容里通过collections（尤其是collections.all或与自身标签匹配的集合）读取自己的templateContent。这与"鸡生蛋"无异，最终会落入第二节的 premature 错误，或经两阶段渲染后升级为第五节提到的循环引用错误。

七、排查清单与实践建议

当你在 buildawesome 项目中看到Tried to use templateContent too early on ...或contains a circular reference (using collections) to its own templateContent.时，可按以下顺序排查：

1. 确认读取位置：templateContent/content是否出现在模板正文、eleventyComputed第一轮或数据文件里？这些位置都先于渲染，属于过早读取；
2. 确认引用对象：读取的是不是"别的模板"的内容？只要目标不是自己（含经collections.all包含自己），就具备两阶段渲染兜底的可能；
3. 确认没有自引用环：目标模板是否打了与当前模板相同的标签，或在collections.all中包含了当前模板？若是，必然升级为UsingCircularTemplateContentReferenceError；
4. 换用合法时机：将读取逻辑迁移到渲染阶段的集合访问、布局的content变量，或第二轮的eleventyComputed（resolveRemainingComputedData阶段）中。

这一整套"夹具 → 测试 → 错误类 → 两阶段渲染"的闭环，正是 buildawesome 对模板内容生命周期管理的完整缩影：用显式错误约束调用时机，用两阶段重渲染提供容错，用循环检测兜底极端情况，从而在"集合内容互相引用"这一静态站点生成的高频需求上，给出既灵活又安全的工程解。

参考阅读：夹具组 test/stubs/prematureTemplateContent/、验收测试 test/TemplateTest.js、属性注入实现 src/Template.js、两阶段渲染 src/TemplateMap.js、错误识别 src/Errors/ErrorUtil.js。

• 前端
• 开发工具