Dify迭代节点配置指南：高效处理批量数据
配置Dify工作流时，一个高频踩坑点在于：不少开发者试图让系统自动处理一批文本、用户数据或文件列表，直接把原始数据连进迭代节点，结果立即报错。原因很简单——迭代节点只接受标准数组格式，普通字符串、JSON对象或单个文件都会被直接拒绝，流程根本无法启动。
理清这套逻辑并不复杂，下面把整个配置路径拆解透彻。
验证输入数据是否为合法数组
打开工作流，找到迭代节点并进入配置面板。第一步：检查上游节点输出的数据结构，必须严格符合["a","b","c"]或[{"id":1,"name":"张三"},{"id":2,"name":"李四"}]这种数组形态。如果上游返回纯文本、单个对象乃至空值，迭代节点会直接中断，报错信息为“Input must be an array”。
常见翻车场景包括：HTTP节点直接请求API后未对原始响应体做JSON解析；代码节点拼装字符串时未调用json.loads()转为列表；从文件读取内容后没按行切分成数组。这些都需要提前做一次格式转换。
两种解法：
解法一：在迭代节点前插入一个代码节点，运行Python脚本做显式转换。脚本如下：
import json
if isinstance(input, str):
try:
input = json.loads(input)
except:
input = [input]
if not isinstance(input, list):
input = [input]
解法二：如果上游是HTTP节点且响应本身就是JSON数组，直接开启“Parse JSON”选项，再用变量提取节点填写$作为JSONPath，即可将根数组原样提取出来。
关键前提： 迭代节点不会自动识别那些“看起来像数组”的字符串。例如"["a","b"]"这类值，必须先执行json.loads()，否则一律被判定为非法输入。
配置迭代路径与当前项变量
在迭代节点的配置中，“数组”字段需填入上游输出的数组变量名，比如{{input_data}}或{{http_response.data}}。
“迭代路径”参数决定每次循环中传递给下游节点的变量名称，默认值为item。也就是说，后续LLM节点的提示词中，可以直接用{{item.name}}或{{item.content}}引用当前元素的对应字段。
如果数组元素本身是对象且带嵌套结构，例如{"user":{"id":1,"email":"a@b.com"}}，可以将迭代路径设为user，下游直接用{{item.id}}即可，无需再写{{item.user.id}}。
注意：迭代路径不支持多层点号写法，比如user.profile这种格式无法识别。只能使用一级字段名，或用.表示根节点。
启用并行模式加速批量任务
操作分三步：
第一步：点击迭代节点右上角的齿轮图标，打开高级设置。
第二步：勾选“启用并行处理”，然后设置并发数。默认值为1（串行模式）。根据模型响应速度和服务器资源，建议设为4～8。并发数超过16时容易触发限流，尤其在免费版API Key场景下更为明显。
第三步：确认下游节点没有强状态依赖。并行模式下，各次迭代彼此独立运行，不能共享变量，也不能同时修改同一条数据库记录。如果需要累计计数或写入同一个Excel文件，必须改为串行模式或引入加锁机制。
这一步看似简单，但有一个细节值得关注：如果下游LLM节点使用了全局术语表变量{{glossary}}，并行时每个子进程都会复制一份副本，互相不会干扰——这一点是安全的。
嵌套循环处理层级数据
当需要遍历“用户→订单→商品”这类三层结构时，必须使用两个迭代节点嵌套：
① 外层迭代节点接收用户数组，迭代路径设为user，下游接入第二个迭代节点；
② 内层迭代节点的“数组”字段填写{{user.orders}}，前提是user对象中确实存在orders字段且类型为数组；
③ 内层迭代路径设为order，再往下可再接第三个迭代节点处理{{order.items}}。
每一层迭代都会生成自己的item变量，作用域彼此隔离。外层的{{item.name}}和内层的{{item.id}}互不冲突。
如果某个用户的orders字段为空或缺失，内层迭代节点会自动跳过执行，不会报错也不中断流程——这是Dify默认的容错行为。
调试与结果聚合
工作流运行后，进入日志面板展开迭代节点，可以看到每个item的独立执行记录，包括输入值、耗时、下游节点输出。失败项会被标红，点击即可查看具体的错误堆栈。
迭代节点最终输出一个数组，元素顺序与输入一致。每个元素对应每个item的完整处理结果。例如输入3个用户，输出为[{"user_id":1,"summary":"OK"},{"user_id":2,"summary":"Failed"},{"user_id":3,"summary":"OK"}]。
如果只想筛选成功项，可以在迭代节点后接一个代码节点，用Python过滤：output = [x for x in input if x.get("summary") == "OK"]。