【n8n教程】：Code节点，处理复杂数据转换！

Code节点是n8n中最强大的工具，它允许你用JavaScript或Python编写自定义代码来处理任何复杂的数据转换任务。

什么是Code节点？为什么你需要它？

Code节点是n8n中用于编写自定义代码的核心工具。想象你是一个数据工程师，某些复杂的数据转换任务用普通的n8n节点无法完成，那么Code节点就是你的救星。它支持多行代码编写，比起表达式编辑器的单行限制更加灵活强大。简单来说，表达式只能处理简单的一行代码，而Code节点可以处理复杂的多行逻辑。

在n8n中，数据以特定的格式在节点之间流动——数组对象格式。所有数据必须遵循这种标准结构，这样每个节点才能识别和处理它。Code节点就是负责将这些数据进行各种转换的工具，比如计算、分组、过滤或合并数据。

Code节点的两种执行模式：选择适合的方式

Code节点提供了两种完全不同的执行模式，这是初学者必须理解的核心概念：

模式1：逐项处理（Run Once for Each Item）

这是默认模式。 当你的工作流中有多个数据项时，Code节点会针对每一项分别执行一次。这就像你有10个订单，Code节点会分别处理每个订单。在这种模式下，你使用的变量是 $input.item.json 来访问当前正在处理的项目的数据。

// 逐项处理模式示例
const orderData = $input.item.json;
const totalPrice = orderData.price * orderData.quantity;

return {
  json: {
    order_id: orderData.id,
    total: totalPrice,
    processed: true
  }
};

这个例子中，如果你有100个订单数据，这段代码会执行100次，每次处理一个订单。这种模式适合处理独立的数据项，每项都需要相同的转换逻辑。

模式2：批量处理（Run Once for All Items）

在这种模式中，Code节点只执行一次，但它能够访问所有输入数据。你可以使用 $input.all() 来获取所有项目，然后进行诸如求和、分组、聚合等操作。

// 批量处理模式示例
const allOrders = $input.all();
const totalRevenue = allOrders.reduce((sum, item) => {
  return sum + (item.json.price * item.json.quantity);
}, 0);

return [{
  json: {
    total_revenue: totalRevenue,
    order_count: allOrders.length
  }
}];

这个例子中，你一次性计算所有订单的总收入。这种模式适合需要全局视角的操作，比如统计、聚合或分组。

数据结构：理解n8n如何存储数据

在开始写代码之前，你必须理解n8n的数据结构——这是最重要的基础概念。

n8n中的所有数据都遵循这样的格式：

[
  {
    "json": {
      "name": "Alice",
      "email": "alice@example.com",
      "age": 28
    }
  },
  {
    "json": {
      "name": "Bob",
      "email": "bob@example.com",
      "age": 35
    }
  }
]

看起来很复杂？其实很简单。每个数据项都是一个对象，包含一个名为 json 的键。所有你的实际数据都放在这个 json 键里面。如果你的Code节点输出数据格式不对，n8n会报错，所以理解这个结构非常关键。

最常见的错误： 初学者经常忘记用 json 键包装数据。如果你直接返回 {name: "Alice"} 而不是 {json: {name: "Alice"}}，Code节点会出错。

访问和处理数据：常用的方法和变量

n8n为Code节点提供了一些内置的方法和变量，让你轻松访问数据。记住这些，你就掌握了50%的Code节点知识：

最常用的四个方法：

// 实例1：逐项处理 - 提取邮箱域名
const email = $input.item.json.email;
const domain = email.split('@')[^1]; // 从 alice@example.com 提取 example.com

return {
  json: {
    email: email,
    domain: domain
  }
};

// 实例2：批量处理 - 统计所有订单
const allItems = $input.all();
const stats = {
  total_items: allItems.length,
  total_value: allItems.reduce((sum, item) => sum + item.json.amount, 0)
};

return [{ json: stats }];

常用数据处理技巧：让代码简洁优雅

技巧1：数据过滤和映射

很多时候你需要筛选数据或改变其形式。使用 map() 和 filter() 是n8n Code节点中最常见的操作：

// 过滤和转换：只保留金额大于100的订单，并提取关键信息
const items = $input.all();
const filtered = items
  .filter(item => item.json.amount > 100)
  .map(item => ({
    json: {
      id: item.json.id,
      amount: item.json.amount,
      status: item.json.amount > 500 ? 'VIP' : 'Standard'
    }
  }));

return filtered;

技巧2：数据分组

当你需要按某个字段分组数据时（比如按类别分组）：

// 按类别分组统计
const items = $input.all();
const grouped = {};

items.forEach(item => {
  const category = item.json.category;
  if (!grouped[category]) {
    grouped[category] = { total: 0, count: 0 };
  }
  grouped[category].total += item.json.price;
  grouped[category].count += 1;
});

// 转换回数组格式
return Object.entries(grouped).map(([category, data]) => ({
  json: {
    category: category,
    total_sales: data.total,
    item_count: data.count
  }
}));

技巧3：安全地访问嵌套数据

你的数据可能包含嵌套结构，比如用户有一个地址对象，地址对象里有城市信息。使用可选链操作符 ?. 和 ?? 操作符可以安全地处理可能不存在的数据：

// 安全地提取嵌套数据，如果不存在就用默认值
const user = $input.item.json;
const city = user?.address?.city ?? 'Unknown';
const email = user?.contact?.email ?? 'no-email@example.com';

return {
  json: {
    name: user.name,
    city: city,
    email: email
  }
};

提高效率的快捷键：让编码更快

n8n Code节点提供了许多键盘快捷键来加速你的编程。以下是最常用的：

基本操作快捷键（Windows/Linux）

高效编辑快捷键

• • Alt + Up/Down：快速移动代码行
• • Shift + Alt + Up/Down：复制代码行到上下
• • Ctrl + Shift + K：删除整行
• • Tab / Shift + Tab：增加/减少缩进

学会这些快捷键会让你的编码速度提升50%以上。尤其是当你需要快速调整大段代码时，快捷键变得非常宝贵。

最常见的错误及解决方案：少走弯路

即使是经验丰富的开发者也会在n8n中犯错。以下是初学者最容易踩的坑：

错误1：返回的数据格式不对

症状： Code节点报错"code doesn't return items properly"

原因： 你没有用 json 键包装数据。

错误代码：

return { name: "Alice" }; // ❌ 错误！

正确代码：

return { json: { name: "Alice" } }; // ✅ 正确

错误2：在批量模式中没有返回数组

症状： 工作流停止运行或输出为空

原因： 在"Run Once for All Items"模式中，必须返回一个数组，即使只有一项。

错误代码：

return { json: { total: 1000 } }; // ❌ 在批量模式中错误

正确代码：

return [{ json: { total: 1000 } }]; // ✅ 返回数组

错误3：使用import/export而不是require

症状： 错误信息"'import' and 'export' may only appear at the top level"

原因： n8n的JavaScript沙箱不支持ES6的import/export语法。

错误代码：

import moment from 'moment'; // ❌ 不支持

正确代码（仅限自托管）：

const moment = require('moment'); // ✅ 使用require
// 注意：n8n Cloud不支持外部模块，只支持内置模块

错误4：忘记处理undefined值

症状： 代码在某些情况下崩溃，但在其他情况下正常运行

原因： 数据可能不完整，某些字段可能不存在。

错误代码：

const name = $input.item.json.user.profile.name; // ❌ 如果user不存在会崩溃

正确代码：

const name = $input.item.json?.user?.profile?.name ?? 'Anonymous';
// ✅ 使用可选链和空值合并操作符

提升技能：从初级到进阶

初级技能（会这些就足够应对80%的需求）

• • 理解两种执行模式的区别
• • 使用 $input.item.json 和 $input.all() 访问数据
• • 使用 map() 和 filter() 进行基本的数据转换
• • 理解并正确返回数据结构
• • 使用 console.log() 进行调试

中级技能（解决复杂问题）

• • 使用 reduce() 进行数据聚合和分组
• • 在Code节点中处理JSON和日期数据
• • 使用引用其他节点的数据进行跨节点操作
• • 理解item linking和pairedItem概念
• • 在Code节点中处理异步操作和API调用

高级技能（成为n8n专家）

• • 使用 getWorkflowStaticData() 存储跨执行的数据
• • 利用自定义函数创建可重用的代码逻辑
• • 优化大型数据集的处理性能
• • 自托管环境中使用外部npm模块
• • 构建复杂的多阶段数据管道

总结

Code节点是n8n中最强大的武器，它将你从"低代码"推向"真正的编程"。一旦你掌握了它，就没有n8n无法解决的数据问题。

官方文档^[1]
n8n系列教程^[2]

引用链接

[1] 官方文档: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/
[2] n8n系列教程: https://www.undsky.com/blog/?category=n8n教程#