核心概念全解

Ch02 核心概念全解

理解 n8n 的六个核心概念是高效使用它的前提：工作流、节点、凭证、执行记录、表达式和变量。本章用大量具体示例解释这些概念，并重点讲解新手最容易卡住的表达式语法。

概念一：工作流（Workflow）

工作流是 n8n 的基本单元，代表一个完整的自动化任务。每个工作流由一个触发器节点（决定何时启动）和若干个处理节点（决定做什么）组成，节点之间通过连线传递数据。

工作流的完整生命周期：

1. 触发（Trigger）：检测到事件（定时到达、Webhook 请求、邮件到达等），工作流开始执行
2. 执行（Execute）：数据从触发节点出发，依次流经每个处理节点
3. 输出（Output）：最后一个节点完成处理，工作流执行结束，结果写入目标系统

工作流有三种运行状态：

• Active（激活）：定时触发和 Webhook 触发正常响应，工作流处于"工作中"状态
• Inactive（停用）：工作流暂停，不响应任何触发，但配置保留
• Error（错误）：上次执行失败，需要排查错误后重新激活

工作流 JSON： n8n 工作流的完整定义以 JSON 格式存储，可通过工作流编辑器右上角 ⋮ → Export 导出。导出的 JSON 包含所有节点配置和连线，可以直接导入到任何 n8n 实例中复现工作流。

概念二：节点（Node）

节点是工作流的构建块。每个节点代表一个操作单元，接收上游数据（Input），执行某种操作，然后输出处理结果（Output）供下游节点使用。

节点类型分类

节点的数据结构

n8n 中所有节点的输入输出都是 JSON 数组，每个元素称为一个 Item（条目）。理解这个数据结构是掌握 n8n 表达式的基础：

// RSS Feed 节点输出示例：一个包含 2 条新闻的 items 数组
[
  {
    "json": {
      "title": "OpenAI 发布 GPT-5",
      "link": "https://example.com/gpt5",
      "pubDate": "2025-04-25T10:00:00Z",
      "content": "OpenAI 今日正式..."
    }
  },
  {
    "json": {
      "title": "Anthropic Claude 4 发布",
      "link": "https://example.com/claude4",
      "pubDate": "2025-04-24T14:30:00Z",
      "content": "Anthropic 宣布..."
    }
  }
]

默认情况下，当一个节点接收到多个 items 时，会对每个 item 分别执行操作（类似 forEach 循环）。这意味着如果上游节点输出了 10 条 RSS 新闻，HTTP Request 节点会自动调用 10 次 API，每次传入一条新闻数据。

概念三：凭证（Credentials）

凭证是 n8n 管理第三方服务 API 密钥、账户信息的安全机制。所有凭证都经过 AES-256 加密存储，不会在执行日志中暴露。

凭证的核心优势是跨工作流复用：你只需要在 Credentials 页面添加一次 OpenAI API Key，所有工作流中的 OpenAI 节点都可以引用这个凭证，无需重复填写。修改凭证时也只需更新一处，所有工作流自动生效。

安全注意： 不要在节点配置的普通文本字段中直接粘贴 API Key——应该始终通过 Credentials 系统管理。n8n 的执行日志会记录节点的输入输出数据，如果 API Key 出现在数据流中，会被明文记录。

概念四：执行记录（Executions）

每次工作流运行都会产生一条执行记录，记录本次运行的时间、状态、每个节点的输入输出数据。执行记录是调试工作流的核心工具。

执行记录的三种状态：

• Success：所有节点正常执行完成
• Error：某个节点抛出错误，工作流中断
• Waiting：工作流在 Wait 节点处暂停，等待外部信号继续

在执行记录列表中点击任意一条记录，可以进入该次执行的节点视图，查看每个节点具体处理了哪些数据。这对于调试数据流向问题非常有用。

概念五：表达式（Expressions）

表达式是 n8n 最强大也是最容易让新手困惑的功能。通过表达式，你可以在任何节点的配置字段中引用上游节点的数据、执行 JavaScript 逻辑、访问环境变量。

表达式语法基础

n8n 表达式写在双花括号内：{{ 表达式内容 }}。在节点配置字段中，点击字段右侧的 = 按钮可以切换到表达式模式。

// 引用当前节点输入数据（最常用）
{{ $json.title }}                      // 当前 item 的 title 字段
{{ $json.user.email }}                 // 嵌套字段访问
{{ $json["order-id"] }}                // 字段名含特殊字符时用方括号

// 引用指定节点的输出数据
{{ $node["HTTP Request"].json.data }}  // 引用名为 "HTTP Request" 节点的 data 字段
{{ $node["Set"].json.userId }}

// 内置变量
{{ $now }}                             // 当前时间（DateTime 对象）
{{ $now.toISO() }}                     // ISO 8601 格式
{{ $now.format("YYYY-MM-DD") }}        // 格式化日期：2025-04-25
{{ $runIndex }}                        // 当前 item 在循环中的序号（从 0 开始）

// JavaScript 表达式
{{ $json.price * 1.1 }}                // 计算：价格加 10%
{{ $json.name.toUpperCase() }}         // 字符串操作
{{ $json.tags.join(", ") }}            // 数组转字符串
{{ $json.amount > 1000 ? "大单" : "普通单" }}  // 三元运算

常用表达式速查表

表达式 vs 固定值： 节点配置字段默认处于"固定值"模式，输入什么就传递什么。点击字段右侧的 = 图标切换到表达式模式后，字段内容会被当作 JavaScript 表达式计算。新手最常见的错误是忘记切换模式，导致 {{ $json.title }} 被当作纯文本传递。

概念六：变量（Variables）

n8n 提供两种类型的变量用于在工作流之间或节点之间共享数据：

全局变量（Variables）

在 n8n 设置面板（Settings → Variables）中定义的全局变量，可以在所有工作流中通过 {{ $vars.变量名 }} 访问。适合存储：

• 环境标识（如 ENV=production）
• 共用配置（如 API 基础 URL、飞书 Webhook 地址）
• 业务常量（如最大重试次数、通知邮箱列表）

// 在节点配置中引用全局变量
{{ $vars.FEISHU_WEBHOOK_URL }}
{{ $vars.API_BASE_URL }}/v1/users
{{ $vars.ENV === "production" ? "prod-db" : "test-db" }}

工作流变量（Static Data）

工作流静态数据是存储在单个工作流中的持久化键值对，使用 Code 节点的 $getWorkflowStaticData() API 读写，常用于记录"上次处理到哪条记录"：

// 读取工作流静态数据
const staticData = $getWorkflowStaticData('global');
const lastProcessedId = staticData.lastId || '0';

// 处理完成后更新静态数据
staticData.lastId = items[items.length - 1].json.id;
staticData.lastRunAt = new Date().toISOString();

return items;

实用技巧： 工作流静态数据是实现"增量同步"的关键——通过记录上次同步的时间戳或最大 ID，下次执行时只拉取新增数据，而不是每次全量重复处理。

数据流动的完整示意

掌握这六个概念之间的关系，就掌握了 n8n 的核心运转逻辑：

1. 工作流被凭证授权后激活，等待触发节点启动
2. 触发产生第一批 items（JSON 数组），进入处理节点链
3. 每个节点通过表达式读取上游 items，处理后输出新的 items
4. 全局变量和工作流静态数据作为共享存储，跨执行周期保存状态
5. 每次执行生成一条执行记录，记录完整的数据快照供调试