Handy n8n - Chapter03 n8n 基本概念

作为一个低代码、无代码的平台，n8n 提供了丰富的功能。本章节课程主要介绍如下概念：

n8n 平台介绍
n8n 触发器节点
n8n 核心节点
n8n 中的代码

n8n 平台介绍

对于本地，云主机，或者 Huggingface space 部署的 n8n 平台，我们需要创建账户。一般地址是类似如下的格式：

本地 - http://127.0.0.1:5678/
云主机 - https://n8n.example.com/
Huggingface space - https://profile-n8n.hf.space/

注册账户

打开对应的地址，弹出注册页面，按表单填写自己的用户名、邮箱、密码等，点击Next
填写自己的邮箱，接受免费 license
检查邮箱，复制 license 信息

界面介绍

登录到系统后，我们可以看到如下的页面

其中主页面上方部分展示系统中工作流的运行统计情况，下部分为工作流、凭据、工作流执行列表等信息。

我们以下列工作流为示例，导入到 n8n 系统中，展示 n8n 系统的界面和功能。

https://tomo.dev/posts/handy-n8n/c03/workflows/test.json

在 n8n 系统中，点击 Start from scratch，介绍两种导入方式：

点击示例工作流下面the workflow’s code以展示工作流代码，点击 Copy 复制代码。

使用复制快捷键Ctrl+V（windows 系统）或者Command (⌘) + V（mac 系统）

拷贝工作流下方的链接，点击 n8n 系统右上方菜单点击Import from URL，粘贴链接。

我们可以看到对应的测试工作流已经展示到 n8n 系统中。需要注意的是 n8n 的工作流不会自动保存，需要手动点击Save按钮或者使用保存快捷键以保存工作流。

点击Execute workflow，我们可以看到工作流开始执行，并在界面下方日志区域看到执行过程的输入输出。

完成工作流的偏排后，可以通过右上角导航栏中的 Inactive 按钮来启动工作流（本示例的工作流使用手动触发，所以无需进行 Active 操作）。

数据结构与执行过程

在 n8n 工作流中，节点间使用对象数组来传递数据，其大致结构如下

[
  {
    // For most data:
    // Wrap each item in another object, with the key 'json'
    json: {
      // Example data
      apple: "beets",
      carrot: {
        dill: 1,
      },
    },
    // For binary data:
    // Wrap each item in another object, with the key 'binary'
    binary: {
      // Example data
      "apple-picture": {
        data: "....", // Base64 encoded binary data (required)
        mimeType: "image/png", // Best practice to set if possible (optional)
        fileExtension: "png", // Best practice to set if possible (optional)
        fileName: "example.png", // Best practice to set if possible (optional)
      },
    },
  },
];

json字段表示文本相关数据，binary字段表示二进制数据，如图片、文件等。其每个数组项可以看作数据库表中的一行数据，如下图所示节点输出了 5 条数据

针对每个数据项需要的操作，n8n 会自动进行处理，这意味着大部分场景不需要在工作流程中专门构建循环。对于数据或者执行流更复杂的控制，将会在后续章节中做更深入的介绍。

n8n 触发器节点

n8n 节点（nodes）是 n8n 的核心，它们是执行特定任务的小组件。每个节点代表一个操作，例如从数据库中获取数据、发送 HTTP 请求或处理 JSON 数据。

n8n 节点分为 trigger 节点和 action 节点。trigger 节点用于启动工作流，而 action 节点用于执行任务。 n8n 内置了很多节点，包括核心节点、集群节点、三方集成节点，同时也支持用户安装社区节点或者开发自定义节点。

本章节主要介绍触发器类型的节点。

任何工作流都需要一个 trigger 节点作为起始节点，一个工作流可以有多个 trigger 节点。在我们开始构建工作流时，需要先选择一个 trigger 节点。点击Add first step… ，工作区右部会显示所有可用的 trigger 节点。

Manual Trigger 手动触发器

Manual Trigger 节点是最简单的 trigger 节点，它不需要任何输入，只需要点击执行按钮即可触发工作流。 Manual Trigger 节点通常用于测试工作流或者需要手动触发的工作流。

添加 Manual Trigger 节点后，点击Execute workflow按钮即可触发工作流。Manual Trigger 节点没有输出，样式如下

https://tomo.dev/posts/handy-n8n/c03/workflows/node_manual_trigger.json

Schedule Trigger 定时触发器

Schedule Trigger 节点用于定时触发工作流，它支持多种定时策略，包括分钟间隔、小时间隔、天间隔等，以及 Cron 类型的配置。如下展示了 Schedule Trigger 节点的配置，其两个规则是等价的。

需要注意的是，Schedule Trigger 触发器的执行时间依赖系统配置的时区信息。对于私有化部署的 n8n，可以通过GENERIC_TIMEZONE和TZ环境变量来配置时区信息。官方 SaaS 版 n8n 的时区可以在管理界面https://app.n8n.cloud/manage 配置

同时 n8n 支持单个工作流配置不同的时区，可以在工作流设置中配置。右上角点击三点菜单，点击Settings，在Timezone配置项中选择时区即可。

点击Execute workflow按钮即可触发工作流。Schedule Trigger 节点输出触发当前工作流的时间信息，如下

[
  {
    "timestamp": "2025-07-09T16:10:00.000+00:00",
    "Readable date": "July 9th 2025, 4:10:00 pm",
    "Readable time": "4:10:00 pm",
    "Day of week": "Wednesday",
    "Year": "2025",
    "Month": "July",
    "Day of month": "09",
    "Hour": "16",
    "Minute": "10",
    "Second": "00",
    "Timezone": "UTC (UTC+00:00)"
  }
]

https://tomo.dev/posts/handy-n8n/c03/workflows/node_schedule_trigger.json

Webhook Trigger Webhook 触发器

Webhook Trigger 节点用于接收 HTTP 请求，从应用程序和服务接收数据触发工作流。添加触发节点 On webhook call，会展示如下配置界面

n8n 为 webhook 触发器生成了一个唯一的 URL 路径，测试 URL 与正式的 URL 有所区别，测试 URL 的路径为webhook-test，正式 URL 中无 test，默认的路径为随机的 UUID。其他的配置项包括 HTTP 方法，Authentication 方式，以及响应方式等。

点击配置面板右上角的Listen for test event，面板左侧会展示测试监听地址，即为配置的回调地址，通过浏览器访问该地址，会看到如下 JSON 返回

{
  "message": "Workflow was started"
}

需要注意的是，该地址访问一次后会失效，需要再次点击Listen for test event重新监听。

对于 Path 配置项，我们可以添加路径路由或者参数，支持的格式如下

/:variable
/path/:variable
/:variable/path
/:variable1/path/:variable2
/:variable1/:variable2

另外，我们可以添加额外的 URL 查询参数进行请求，如在 URL 结尾添加?p1=a&p2=b 参数。

对于返回 webhook 触发器的返回，n8n 提供三种方式

立即 Immediately：Webhook 节点返回响应代码和消息{"message":"Workflow was started"}。
当最后一个节点完成时 When Last Node Finishes：Webhook 节点返回响应代码和在工作流程中最后一个执行的节点的数据输出。
使用’Respond to Webhook’节点：Webhook 节点按‘响应 Webhook’节点中的定义进行响应。

对于简单的场景，我们可以使用 Immediately：Webhook 选项，配合额外的配置进行处理。n8n 支持如下配置项

Allowed Origins (CORS)
Field Name for Binary Data
Ignore Bots
IP(s) Whitelist
No Response Body
Raw Body
Response Code
Response Data
Response Headers

一个完整的测试请求 URL 例子：https://n8n.example.com/webhook-test/UUID/test/v1?p1=a&p2=b，其中/test/v1中的v1为路径参数。

使用 CURL 命令，请求该地址，最终展示的配置及节点输出如下

具体配置可以参考如下的节点

https://tomo.dev/posts/handy-n8n/c03/workflows/node_webhook_trigger.json

对于复杂场景，如响应内容需要基于工作流运行情况进行调整，或者需要使用工作流最后节点的输出，可以使用Respond to Webhook或者When Last Node Finishes的响应方式进行定制。

Chat Trigger 聊天触发器

聊天触发器的使用场景为聊天机器人或者其他对话形式的交互工作流。在工作流中添加On chat message节点来使用该触发器。聊天触发器需要连接 Agent 节点或者集群节点。

需要注意的是，每次用户发送消息都会触发工作流，如果是 SaaS 版本，需要注意套餐的配额限制。

聊天触发器可以视为一种特殊的 webhook 触发器。如果只希望在工作区人工触发，可以设置聊天触发器为非公开访问。如果配置允许公开访问，n8n 将生成一个唯一的 URL，用户可以通过该 URL 打开聊天交互界面（Hosted Chat 模式）。

公开访问的 URL 只能在工作流激活时使用，如果工作流未激活，公开访问的 URL 会返回 404 错误。

{
  "code": 404,
  "message": "The requested webhook \"GET UUID/chat\" is not registered.",
  "hint": "The workflow must be active for a production URL to run successfully. You can activate the workflow using the toggle in the top-right of the editor. Note that unlike test URL calls, production URL calls aren't shown on the canvas (only in the executions list)"
}

聊天触发器配置示例如下：

通过浏览器访问聊天触发器提供的 URL，可以看到一个简易的聊天界面，输入问题可以触发工作流，然后展示工作流的输出结果。

查看工作流的执行，可以看到执行记录和日志

完整的工作流示例如下

https://tomo.dev/posts/handy-n8n/c03/workflows/node_chat_trigger.json

n8n 核心节点

除了触发器节点，n8n 还包含许多核心节点，这些节点可以执行各种任务。本章节介绍相关的核心节点，包括数据处理节点、控制流节点、HTTP 请求节点等。

本章节介绍的核心节点，可以参考如下的工作流，先行导入，基于示例进行对照学习：

https://tomo.dev/posts/handy-n8n/c03/workflows/n8n_node_demo.json

Data transformation 数据处理节点

数据是工作流流转的核心，数据处理节点用于对数据进行处理，包括数据拆分、合并、赋值等。选择Data transformation大类，可以看到如下的数据处理节点列表：

本章节介绍其中的 Edit Fields 和 Split Out 节点。

Edit Fields 变量赋值节点

使用 Edit Fields 来给工作流中的数据赋值。该节点可以更改已有的数据，或者添加新的数据。

该节点可以选择两种变量赋值模式：手动映射 Manual Mapping，和 JSON 输出模式。如下是手动映射模式，通过指定字段的名称以及值来赋值：

其等价的 JSON 输出模式的代码如下：

{
    "number": {{ Array.from({ length: 10 }, (_) => Math.floor(Math.random() * 100)) }}
}

该例子中将number字段的值赋值为一个长度为 10 的随机数组。

Split Out 数据拆分节点

Split Out 节点用于将包含数组字段的数据拆分为多个部分。Include配置项作用为您希望 n8n 如何在每个新单独项中保留输入数据中的其他字段。

No Other Fields: 不包含其他字段
All Other Fields: 包含所有其他字段
Selected Other Fields: 指定包含的字段

如下是 Split Out 节点的配置示例，节点输入为：

{
  "number": [81, 61, 53, 18, 47, 56, 63, 45, 25, 15],
  "field1": "test"
}

Split Out 将其中number字段拆分为 10 项，且根据Selected Other Fields配置的字段，将field1字段包含在每一项中。

控制流节点

控制流节点用于控制流程的执行，包括条件判断、循环、分支等。选择Flow大类，可以看到如下的控制流节点列表：

本节介绍其中的 If 和 Merge 以及 Loop 节点。

If 条件判断节点

If 节点用于根据比较操作有条件地拆分工作流程。不同的数据类型支持不同的比较操作，常见的数据类型如String, Number, Boolean, Array, Object等。If 节点还支持添加多个条件判断，对于所有的条件，支持选择AND和OR两种逻辑运算符，表示所有条件必须满足或者满足任意一个条件。

如下是 If 节点的配置示例，节点通过判断输入的number值是否小于 50 将数据拆分为True Branch 和False Branch两个分支。

Merge 数据合并节点

Merge 节点用于将多个数据项合并为一个数据项。该节点可以合并来自多个节点的数据，该节点会等待所有上游节点数据可用后执行。Merge 节点典型的应用场景如合并获取的多个网页内容然后提交至 AI 节点进行总结。

Merge 节点有如下几种数据合并方式：

Append - 追加，保留所有数据，并将数据项依次追加到结果中
Combine - 合并，基于Combine By选项决定如何合并数据
SQL Query - 使用 SQL 语言来合并数据
Choose Branch - 选择分支，选择输入 1 或者输入 2 的数据，或者输出空项

如下是 Merge 节点的配置示例，节点使用追加模式将 If 节点两个分支的数据项合并为一个数据项。

Loop 循环节点

默认情况下，n8n 节点设计为循环处理输入项列表，所以一般情况下通常在工作流中不需要循环节点。但一些特殊情况下，如节点只处理输入项列表中的第一个值（如 RSS 节点），此时可以使用 Loop 节点。

如下是 Loop 节点的配置示例，节点使用循环处理输入的number字段，每批次处理 2 个数据项。

HTTP 请求节点

HTTP 请求节点是 n8n 中最灵活的节点之一。它允许您进行 HTTP 请求，以从任何具有 REST API 的应用程序或服务中查询数据。您可以将 HTTP 请求节点用作常规节点或附加到 AI Agent 节点以作为工具使用。

HTTP 请求节点支持常见的 HTTP 相关的各项配置项，如请求方法、请求 URL、认证、请求头、请求体等。

如下是 HTTP 请求节点的配置示例，节点使用 GET 方法请求 https://httpbin.org 服务的 API，并传递nubmer字段作为 URL 的查询参数。

参考示例

在学完相关的核心节点后，可以尝试运行本章开头所导入的工作流，其完整的执行结果如下

另外附上官方文档供参考：

n8n 中的代码

n8n 是一个低代码平台，意味着大部分时候可以通过拖拽节点来创建工作流，而不需要编写代码。 n8n 也支持通过代码来扩展工作流的功能。

n8n 中的代码在两个地方使用，一个是"代码节点"，另一个在表达式中。表达式只支持 JavaScript，代码节点则支持 JavaScript 及 Python 语言。

Expressions 表达式

Expressions 表达式是 n8n 中最常用的代码形式，被实现在 n8n 所有的节点中，用于处理数据或者引用变量。通过表达式，工作流节点的配置参数可以基于前序节点的输出、工作流的元信息、以及环境变量来动态生成。

Expressions 表达式中只允许 JavaScript 代码，其使用模板语言 tournament 来实现，实际代码包含在{{ }}中。同时 n8n 内置了一些函数与变量，可以方便的在表达式中使用。

在前序的章节中我们已经使用过表达式，如中Edit Fields 节点中，我们使用表达式来生成随机数组：

Array.from({ length: 10 }, (_) => Math.floor(Math.random() * 100));

需要注意的是，表达式只允许单个语句，意味着在表达式中不允许变量赋值、函数定义等语句。如下是无效的表达式：

// This example is split over multiple lines for readability
// It's still invalid when formatted as a single line
{{
  function example() {
    let end = DateTime.fromISO('2017-03-13');
    let start = DateTime.fromISO('2017-02-13');
    let diffInMonths = end.diff(start, 'months');
    return diffInMonths.toObject();
  }
  example();
}}

上述例子如果期望在表达式中运行，可以改成如下形式：

{{DateTime.fromISO('2017-03-13').diff(DateTime.fromISO('2017-02-13'), 'months').toObject()}}

所以，对于复杂的表达式，建议使用Code节点来处理。

Code 节点

Code 节点允许用户编写 JavaScript 或 Python 代码来处理数据。Code 节点有两种运行模式，

Run Once for All Items：默认模式，所有输入数据会作为数组传递给代码，代码只执行一次
Run Once for Each Item：针对每个输入的数据项都运行代码

Python 代码使用 JavaScript 的pyodide 库来执行，其执行效率低于 JavaScript 代码。所以如果追求极致的性能，建议使用 JavaScript 代码。

Code 节点出于安全的考虑，不允许读写系统文件以及发起 HTTP 请求，相关的操作需要通过 n8n 的其他节点来实现。

如果想调试代码，或者观测代码处理过程中的数据，可以通过console.log()或者print()，将调试信息输出到浏览器控制台中。

内置变量与函数

n8n 内置了一些函数与变量，可以方便的在代码中使用，JavaScript 以及 Python 使用不同的命名方式进行变量获取，JavaScript 使用$前缀来引用内部变量，Python 使用_前缀。如下是一些常用的变量（所有变量列表可以参考官方文档https://docs.n8n.io/code/builtin/overview/ ）：

JavaScript	Python	描述
`$input.item`	`_input.item`	当前节点关联的输入数据
`$input.all()`	`_input.all()`	当前节点关联的所有输入
`$input.first()`	`_input.first()`	当前节点关联的第一个数据项
`$json`	`_json`	`$input.item.json`或者`_input.item.json` 的快速访问
`$("<node-name>").all()`	`_("<node-name>").all()`	获取特定节点的全部输入
`$now`	`_now`	当前时间，`DateTime.now()`

Code 节点的返回需要符合 n8n 要求的数据结构，即返回一个数组，数组中的每一项为一个对象，对象中包含json字段。在最新的 n8n 版本中，n8n 对返回的数据做了部分自动补全，如添加缺失的json字段，或者将返回的对象包成单一数据数组。如下两种返回方式是等效的：

return [{ json: { name: "John" } }];
return { name: "John" };

引入外部库

如果需要在 Code 节点中引入外部库，JavaScript 与 Python 的处理方式不同。

对于 Python 而言，n8n 使用 pyodide 库支持相关的代码执行，pyodide 本身有受限制的内置库，包含常见的如numpy、pandas、beautifulsoup4等库。pyodide 库的完整列表如下：https://pyodide.org/en/stable/usage/packages-in-pyodide.html 。在 Python 代码节点中第一次import相关的库会自动下载。

需要注意的是，官方在处理安全性问题时限制了部分库的引用，导致 n8n 中间部分版本 pyodide 支持的库无法使用，n8n 实例需要升级到1.102.0版本以上正常使用，详细信息可以参考https://github.com/n8n-io/n8n/issues/16532

对于 JavaScript 而言，出于安全性考虑，n8n 需要配置环境变量来允许引入外部库。如需要moment 及lodash库，可以配置环境变量 NODE_FUNCTION_ALLOW_EXTERNAL=moment,lodash。

参考示例

以下是一个使用 Code 节点的示例，包括 JavaScript 及 Python 两个代码节点，外部库的引入，调试信息，以及返回数据的处理

https://tomo.dev/posts/handy-n8n/c03/workflows/n8n_code_node.json

另外附上官方文档供参考：

Handy n8n - Chapter03 n8n 基本概念

n8n 基本概念介绍，包括平台介绍、触发器节点、核心节点、代码等

目录

n8n 平台介绍

注册账户

界面介绍

数据结构与执行过程

n8n 触发器节点

Manual Trigger 手动触发器

Schedule Trigger 定时触发器

Webhook Trigger Webhook 触发器

Chat Trigger 聊天触发器

n8n 核心节点

Data transformation 数据处理节点

Edit Fields 变量赋值节点

Split Out 数据拆分节点

控制流节点

If 条件判断节点

Merge 数据合并节点

Loop 循环节点

HTTP 请求节点

参考示例

n8n 中的代码

Expressions 表达式

Code 节点

内置变量与函数

引入外部库

参考示例