Description

n8n-nodes-while

这是一个 n8n 社区节点，允许你在 n8n 工作流中循环处理数据项。

n8n 是一个公平代码许可的工作流自动化平台。

目录

• 安装
• 功能特性
• 使用方法
• 节点参数
• 使用示例
• 版本信息
• 兼容性
• 开发
• 许可证
• 支持

安装

通过 n8n 社区节点安装（推荐）

1. 在 n8n 中打开 Settings > Community Nodes
2. 选择 Install
3. 在 Enter npm package name 中输入 n8n-nodes-while
4. 同意使用社区节点的风险
5. 点击 Install

安装完成后，重启 n8n，节点将出现在节点面板中。

手动安装

在 n8n 根目录执行：

npm install n8n-nodes-while

Docker 安装

在 n8n Dockerfile 中的字体安装命令之前添加：

RUN cd /usr/local/lib/node_modules/n8n && npm install n8n-nodes-while

功能特性

✨ 核心功能

• 循环处理数据项 – 逐个或分批处理输入的 items
• 可配置批次大小 – 自定义每次循环处理的 item 数量
• 双输出机制 – loop 输出用于循环，done 输出用于完成
• 数组字段支持 – 从输入数据中提取数组进行循环
• 表达式支持 – 支持使用 n8n 表达式指定数组
• 状态保持 – 自动保持循环状态，支持复杂的循环逻辑

🎯 适用场景

• 批量处理 API 请求（避免速率限制）
• 逐个处理数据库记录
• 对每个元素执行复杂的数据转换
• 处理嵌套数组数据
• 需要对每个 item 进行独立的工作流处理

使用方法

基本循环

While 节点有两个输出端口：

• loop (第一个输出) – 循环进行时的数据输出
• done (第二个输出) – 循环完成时的数据输出

关键：必须将 loop 输出连接回 While 节点的输入，形成循环！

工作流结构

┌──────────────┐
│ 数据源节点    │
└──────┬───────┘
       │
       ↓
┌──────────────┐  ← ← ← ← ← ← ← ← ← ← ← ← ← ←
│ While 节点   │                             ↑
└──┬────────┬──┘                             ↑
   │        │                                ↑
loop│        │done                           ↑
   │        │                                ↑
   ↓        ↓                                ↑
┌─────────┐ ┌─────────────┐                 ↑
│ 处理节点 │ │ 最终结果    │                 ↑
└────┬────┘ │   节点      │                 ↑
     │      └─────────────┘                 ↑
     │                                      ↑
     └──────────────────────────────────────┘

基本示例

1. 添加数据源节点（如 Code 节点）生成测试数据
2. 添加 While 节点，设置 Batch Size 为 1
3. 添加处理节点（用于处理每个 item）
4. 重要：将处理节点的输出连接回 While 节点的输入
5. 将 While 节点的 done 输出连接到最终结果节点

节点参数

Batch Size（批次大小）

• 类型: Number
• 默认值: 1
• 描述: 每次迭代返回的 item 数量
• 最小值: 1

示例：

• Batch Size = 1: 每次处理 1 个 item
• Batch Size = 5: 每次处理 5 个 items

Options（可选参数）

Reset（重置）

• 类型: Boolean
• 默认值: false
• 描述: 是否重置节点状态并重新初始化

使用场景：当需要在同一工作流中重新开始循环时

Array Field Name（数组字段名）

• 类型: String
• 默认值: 空
• 描述: 要循环处理的数组字段名或表达式

支持两种方式：

1. 字段名 (字符串)

   Array Field Name: users
   

   从输入数据的 users 字段中提取数组

2. 表达式 (n8n 表达式)

   Array Field Name: {{ $json.users }}
   

   直接传入数组对象

留空时：循环处理输入的 items（默认行为）

使用示例

示例 1: 基本循环处理

输入数据（Code 节点）：

return [
  { json: { id: 1, name: "Alice", score: 85 } },
  { json: { id: 2, name: "Bob", score: 92 } },
  { json: { id: 3, name: "Charlie", score: 78 } }
];

While 节点配置：

• Batch Size: 1
• Array Field Name: 留空

处理节点（Code 节点）：

const item = $input.first().json;

return [{
  json: {
    id: item.id,
    name: item.name,
    score: item.score,
    grade: item.score >= 90 ? 'A' : item.score >= 80 ? 'B' : 'C',
    processed: true
  }
}];

输出结果：

[
  { "id": 1, "name": "Alice", "score": 85, "grade": "B", "processed": true },
  { "id": 2, "name": "Bob", "score": 92, "grade": "A", "processed": true },
  { "id": 3, "name": "Charlie", "score": 78, "grade": "C", "processed": true }
]

示例 2: 使用数组字段（字段名方式）

输入数据（Code 节点）：

return [{
  json: {
    orderID: "ORD-12345",
    products: [
      { sku: "PROD-001", name: "Laptop", price: 1000, quantity: 1 },
      { sku: "PROD-002", name: "Mouse", price: 25, quantity: 2 },
      { sku: "PROD-003", name: "Keyboard", price: 75, quantity: 1 }
    ],
    customer: "John Doe"
  }
}];

While 节点配置：

• Batch Size: 1
• Array Field Name: products

处理节点（Code 节点）：

const product = $input.first().json;

return [{
  json: {
    sku: product.sku,
    productName: product.name,
    unitPrice: product.price,
    quantity: product.quantity,
    totalPrice: product.price * product.quantity
  }
}];

输出结果：

[
  { "sku": "PROD-001", "productName": "Laptop", "unitPrice": 1000, "quantity": 1, "totalPrice": 1000 },
  { "sku": "PROD-002", "productName": "Mouse", "unitPrice": 25, "quantity": 2, "totalPrice": 50 },
  { "sku": "PROD-003", "productName": "Keyboard", "unitPrice": 75, "quantity": 1, "totalPrice": 75 }
]

示例 3: 使用数组字段（表达式方式）

输入数据（Code 节点）：

return [{
  json: {
    apiResponse: {
      status: "success",
      users: [
        { userId: 1, email: "alice@example.com", active: true },
        { userId: 2, email: "bob@example.com", active: false },
        { userId: 3, email: "charlie@example.com", active: true }
      ],
      totalCount: 3
    }
  }
}];

While 节点配置：

• Batch Size: 1
• Array Field Name: {{ $json.apiResponse.users }}

处理节点（Code 节点）：

const user = $input.first().json;

if (user.active) {
  return [{
    json: {
      userId: user.userId,
      email: user.email,
      status: "Active user - send welcome email"
    }
  }];
} else {
  return [{
    json: {
      userId: user.userId,
      email: user.email,
      status: "Inactive user - skip"
    }
  }];
}

示例 4: 批量处理

输入数据：100 个 items

While 节点配置：

• Batch Size: 10

结果：循环 10 次，每次处理 10 个 items

使用场景：

• 批量调用 API（每次发送 10 条记录）
• 批量插入数据库
• 避免单次处理过多数据导致超时

示例 5: 处理简单值数组

输入数据（Code 节点）：

return [{
  json: {
    numbers: [10, 20, 30, 40, 50]
  }
}];

While 节点配置：

• Batch Size: 1
• Array Field Name: numbers

每次循环输出：

{ "value": 10 }
{ "value": 20 }
{ "value": 30 }
{ "value": 40 }
{ "value": 50 }

说明：简单值（数字、字符串）会被自动包装为 { value: 元素值 } 格式

版本信息

v1.0.0 (2025-10-05)

初始发布

功能特性

• ✅ 基本循环功能
• ✅ 可配置批次大小
• ✅ 双输出机制（loop 和 done）
• ✅ 数组字段支持（字段名和表达式）
• ✅ 简单值数组自动包装
• ✅ 循环状态管理
• ✅ Reset 重置功能

技术实现

• TypeScript 实现
• 完整的类型定义
• 深拷贝数据，避免引用问题
• 支持 binary 数据传递
• pairedItem 正确设置

已知限制

• 不支持无限循环（需要有明确的循环次数）
• 循环状态在工作流重启后会重置

兼容性

n8n 版本	插件版本	状态
1.0.0+	1.0.0	✅ 测试通过
0.x.x	1.0.0	⚠️ 未测试

推荐 n8n 版本: 1.0.0 或更高

常见问题

Q1: While 节点只处理了第一个 item？

A: 确保将处理节点的输出连接回 While 节点的输入，形成循环。

正确连接：

While (loop) → Process Node → While (input)
      ↑_________________________|

Q2: 如何停止循环？

A: While 节点会自动在处理完所有 items 后停止，最后一批数据从 done 输出。

Q3: 可以在循环内部使用其他节点吗？

A: 可以！你可以在 loop 输出和 While 输入之间添加任意多个节点，只要最后连回 While 即可。

Q4: 支持嵌套循环吗？

A: 支持。可以在一个 While 循环内部再嵌套另一个 While 节点。

Q5: 如何处理大量数据避免内存问题？

A: 设置合适的 Batch Size，分批处理。例如有 1000 条数据，设置 Batch Size = 100，将循环 10 次。

Q6: Array Field Name 使用字段名和表达式有什么区别？

A:

• 字段名 (users): 简单，适合固定的字段路径
• 表达式 ({{ $json.users }}): 灵活，可以使用复杂的表达式、嵌套路径

开发

克隆项目

git clone https://github.com/your-username/n8n-nodes-while.git
cd n8n-nodes-while

安装依赖

npm install

构建

npm run build

开发模式

npm run dev

测试

在本地 n8n 实例中测试：

1. 链接到本地 n8n：

npm link
cd ~/.n8n/nodes
npm link n8n-nodes-while

2. 重启 n8n

项目结构

n8n-nodes-while/
├── nodes/
│   └── While/
│       ├── While.node.ts      # 节点实现
│       └── While.node.json    # 节点元数据
├── dist/                      # 编译输出
├── package.json
├── tsconfig.json
├── gulpfile.js
└── README.md

贡献

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

路线图

未来计划的功能：

• 支持条件循环（while 条件为真时继续）
• 添加循环计数器变量
• 支持并行批处理
• 添加循环进度追踪
• 性能优化

许可证

MIT

Copyright (c) 2025

支持

文档

• n8n 社区节点文档
• n8n 工作流文档

获取帮助

• 🐛 报告 Bug
• 💡 功能请求
• 💬 讨论
• 📧 Email: yfwlbjf@gmail.com

社区

• n8n 社区论坛
• n8n Discord

致谢

感谢 n8n 团队创建了这个强大的工作流自动化平台！

本节点的实现参考了官方的 Loop Over Items 节点。

---

如果觉得这个节点有用，请给个 ⭐️！

---

Made with ❤️ for the n8n community