Nunjucks模板循环报错问题排查咨询

这种“单个渲染正常、一循环就崩”的情况真的很磨人！我之前做项目也碰到过类似的坑，结合经验给你梳理几个大概率的方向和排查步骤：

1. 数组内部存在异常数据项 #

单个渲染时你用的是正常结构的对象，但数组里可能混了null、undefined或者结构不完整的元素——模板里访问这些异常项的属性时就会报错，而单个渲染时没碰这些项所以没问题。

排查方法：

• 先在控制台打印整个数组：console.log('待渲染数组:', yourArray)，逐行检查每一项的类型和结构，有没有和预期不符的元素；
• 做个小测试：把数组改成只包含单个能正常渲染的项，用循环渲染，如果正常，再逐步添加其他项，找到触发报错的那个“坏项”；
• 如果数组是接口返回的，检查接口响应的JSON结构，有没有嵌套字段缺失的情况。

2. 循环指令/语法的细节错误 #

不同框架的循环语法有严格要求，单个渲染时不用循环所以没暴露问题，循环时就触发了语法或规则错误：

• 比如Vue里的v-for没加唯一的key（或者key重复），虽然控制台可能只提示警告，但极端情况会导致渲染崩溃；
• 比如React里用map循环时，key用了不稳定的index（当数组有增删排序时），或者循环变量和外层变量重名；
• 还有可能是循环的遍历方式写错了，比如把in写成of（JS里的遍历语法差异）。

排查方法：

• 对照框架文档检查循环语法是否完全正确，比如Vue的v-for="(item, index) in list"，React的array.map((item) => <Component key={item.id} />)；
• 把key换成数组项的唯一标识（比如id），不要用index试试；
• 暂时去掉循环里的复杂逻辑，只渲染最简单的内容（比如{{ item }}或{item}），看循环是否能正常运行。

3. 模板内部的逻辑在循环时触发隐性错误 #

模板里的某些表达式，在处理单个正常项时没问题，但碰到数组里的特殊项就会报错——比如你写了item.user.name，但某条数据的item.user是null，单个渲染时item.user存在，所以没报错，循环时就崩了。

排查方法：

• 简化模板到极致：比如循环里只渲染item的字符串形式，看是否正常；
• 逐步加回模板的内容，每加一部分就测试一次，定位到触发报错的那行代码；
• 给可能出错的表达式加防御性判断，比如Vue里用{{ item.user?.name }}，React里用{item.user?.name}，先让渲染跑起来，再看哪个字段有问题。

4. 框架吞掉了详细报错信息 #

有些框架的错误边界或调试模式会隐藏详细的报错内容，导致你看到的报错信息不全，谷歌搜不到也正常。

排查方法：

• 打开浏览器开发者工具的Console面板，展开所有折叠的报错信息和调用栈，框架通常会在这里输出完整的错误详情；
• 在循环的回调里手动加try-catch捕获错误，比如React里：

  yourArray.map((item) => {
    try {
      return <YourTemplateComponent key={item.id} data={item} />;
    } catch (e) {
      console.error('渲染单个项失败:', item, e);
      return <div>渲染出错</div>;
    }
  });
  

  Vue里可以在组件的errorCaptured钩子中捕获错误，这样能精准定位到哪个数组项出了问题，以及具体的错误原因。

5. 数组不是标准的可遍历对象 #

有时候你拿到的“数组”其实是类数组对象（比如DOM集合、接口返回的伪数组），单个取元素没问题，但框架的循环指令无法正常遍历这类对象，导致报错。

排查方法：

• 用Array.isArray(yourArray)检查是否为标准数组；
• 如果是类数组，转成标准数组再试：const realArray = Array.from(yourArray) 或者 const realArray = [...yourArray]。

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