Article

模型工作流 N8N

更新于：2026-07-20

第一章：n8n 基础入门

1.1 n8n 简介与核心概念

概念名称说明注意事项
n8n一个开源的低代码工作流自动化工具，支持通过图形化界面连接不同服务和 API。需要基本的 Web 和 API 知识才能高效使用。
工作流（Workflow）由多个节点按逻辑顺序连接而成的自动化流程，是 n8n 的核心执行单元。一个工作流必须包含至少一个 Trigger 节点才能被激活（除非手动执行）。
节点（Node）工作流中的功能模块，每个节点代表一个操作（如发送 HTTP 请求、读取数据库等）。节点之间通过数据传递连接，输出格式通常为 JSON 数组。
执行（Execution）工作流的一次运行实例，包含输入、输出、时间戳和状态（成功/失败）。可在 Executions 页面查看历史记录，用于调试和监控。
凭据（Credentials）用于安全存储外部服务的认证信息（如 API Key、OAuth Token）。凭据在数据库中加密存储，不应硬编码在节点参数中。
Trigger 节点触发工作流开始执行的起始节点（如 Webhook、Schedule、Manual Trigger）。每个工作流只能有一个激活的 Trigger 节点。

1.2 安装与启动方式（本地/云/Docker）

步骤名称操作细节注意事项
本地安装（npm）在终端执行：npm install n8n -g；然后运行：n8n start需预先安装 Node.js（建议 v18+）和 npm。
Docker 安装执行命令：docker run -it --rm --name n8n -p 5678:5678 n8nio/n8n首次运行会自动初始化；如需持久化数据，应挂载卷（-v）。
使用 Docker Compose编写 docker-compose.yml 文件，定义 n8n 服务及数据库依赖，然后运行 docker-compose up推荐用于生产环境，便于管理配置和数据持久化。
云部署（n8n.cloud）访问 https://n8n.cloud 注册账号，创建新实例，通过 Web 界面直接使用免运维，但高级功能可能需要付费订阅。
环境变量配置可通过设置 N8N_BASIC_AUTH_USER、N8N_HOST 等环境变量自定义行为修改端口或启用用户认证时必须正确设置环境变量。
启动后访问地址默认访问 http://localhost:5678（若本地运行）若端口被占用，可通过 --port 参数指定其他端口。

1.3 用户界面概览（Editor、Workflow、Executions 等）

概念名称说明注意事项
Editor（编辑器）主工作区，用于拖拽节点、连接流程、配置参数的可视化界面。支持快捷键（如 Ctrl/Cmd + S 保存），建议熟悉布局后再复杂建模。
Workflow 列表页展示所有已创建工作流的面板，可启用/禁用、复制、删除工作流。禁用的工作流不会响应 Trigger，但数据仍保留。
Executions 页面显示所有工作流执行历史，包括状态、耗时、输入输出数据。可点击具体执行项查看详细日志，用于排查错误。
Credentials 管理页用于创建和管理外部服务的认证凭据（如 Gmail、Slack、Airtable 等）。凭据创建后可在多个节点中复用，提升安全性与维护性。
Settings（设置）包含用户账户、API 访问、Webhook URL 基础路径等全局配置。修改 Webhook 基础路径会影响已有 Webhook 节点的 URL。
Templates（模板）官方提供的预设工作流模板，可一键导入快速搭建常见自动化场景。部分模板需登录或连接特定服务后才能使用。

1.4 创建第一个工作流（Hello World 示例）

步骤名称操作细节注意事项
步骤 1：创建新工作流在 Editor 页面点击 ”+” 新建空白工作流。工作流默认未命名，建议及时保存并命名。
步骤 2：添加 Manual Trigger 节点在节点面板搜索 “Manual Trigger”，拖入画布并配置（无需参数）。此节点用于手动触发测试，不适用于自动运行场景。
步骤 3：添加 Set 节点搜索并添加 “Set” 节点，连接到 Manual Trigger；在 Parameters 中设置字段如 {"message": "Hello, n8n!"}Set 节点用于构造或修改数据，输出为单个 item。
步骤 4：添加 Debug Helper（可选）添加 “Debug Helper” 或使用内置执行日志查看输出。实际部署时可替换为 HTTP Request、Email 等真实动作节点。
步骤 5：执行工作流点击 Manual Trigger 节点上的 “Execute Workflow” 按钮。执行结果将在右侧 “Execution Debug” 面板中显示。
步骤 6：查看执行结果在 Executions 页面或 Editor 底部查看输出数据是否包含 message 字段。若无输出，检查节点连接是否正确，或是否有红色错误提示。

第二章：节点（Nodes）详解

2.1 节点类型与分类（Trigger、Regular、Core 等）

类型名称说明注意事项
Trigger 节点工作流的起点，负责在特定事件发生时启动执行（如定时、Webhook、手动触发）。每个工作流只能有一个激活的 Trigger 节点；未连接 Trigger 的工作流无法自动运行。
Regular 节点执行具体操作的中间节点，如发送请求、处理数据、调用 API 等。可串联多个 Regular 节点；每个节点接收上一节点输出作为输入。
Core 节点n8n 内置的基础功能节点，由官方维护，覆盖通用自动化场景（如 Set、IF、Merge）。Core 节点无需额外安装，开箱即用，稳定性高。
Action 节点通常指对第三方服务执行写操作的节点（如创建 Slack 消息、新增 Google Sheet 行）。多数 Action 节点需预先配置对应服务的 Credentials。
Source 节点用于从外部系统拉取数据的节点（如读取数据库、获取邮件、查询 API）。部分 Source 节点可作为 Trigger（如 “Polling” 模式），但性能需注意。
Subworkflow 节点即 “Execute Workflow” 节点，用于调用其他工作流，实现模块化复用。被调用的工作流必须存在且已保存；支持传参和接收返回值。

2.2 常用内置节点功能概览（Webhook、HTTP Request、Function 等）

节点名称用途代码示例 / 配置要点注意事项
Webhook接收外部 HTTP 请求并触发工作流，支持 GET/POST 等方法。路径设为 /myhook，方法选 POST；触发后请求体自动转为 JSON 输入。Webhook URL 由 n8n 自动生成，含唯一路径；建议启用身份验证（如 token）。
HTTP Request向任意 URL 发起 HTTP 请求，支持 GET/POST/PUT/DELETE 等。Method: POST；URL: https://api.example.com/data；Body Parameters: {"key":"value"}支持 OAuth2、Basic Auth 等认证方式；响应自动解析为 JSON（若格式合法）。
Function使用 JavaScript 编写自定义逻辑，处理输入数据并返回新数据。return [{ json: { result: items[0].json.input * 2 } }];必须返回数组格式；items 是输入数据；不支持异步 await（除非启用 async mode）。
Code功能同 Function，但界面更简洁，适合短脚本。const value = $input.json.value; return { new_value: value + 10 };实际是 Function 节点的简化别名；行为一致。
Set构造或修改当前数据项的字段，常用于初始化或标准化数据结构。设置字段 message = "Hello"，mode = "manual"支持 “Keep Only Set” 模式，仅保留设定字段。
IF根据条件分支执行不同路径（true/false 分流）。条件表达式：{{$node["Set"].json["score"]}} > 80条件为真走第一条输出，假走第二条；支持复杂表达式。
Merge合并两个分支的数据，支持多种策略（Append、Combine、Keep Key Match）。Mode: Combine；将 A 分支的 name 与 B 分支的 email 合并为单个对象。两路输入需提前通过 Branch 或 Split 节点分离；注意数据对齐逻辑。
Cron定时触发工作流（类似 Linux crontab）。Cron Expression: 0 9 * * 1（每周一上午9点）时区默认为服务器本地时间；可通过环境变量 N8N_TIMEZONE 修改。

2.3 自定义节点开发基础（Node Development Intro）

概念名称说明注意事项
自定义节点（Custom Node）用户通过 TypeScript/JavaScript 开发的扩展节点，可打包为 npm 包供 n8n 加载。需遵循 n8n 节点开发规范，包含 node.json 和实现文件。
node.json描述节点元数据的配置文件，定义名称、图标、参数、输入输出等。必须包含 displayName、name、group、description、version 等字段。
execute() 方法节点的核心逻辑函数，接收 inputs 并返回处理后的数据。返回值必须是 INodeExecutionData[][] 类型（二维数组）。
Credentials 支持自定义节点可声明所需凭据类型，在 UI 中自动关联 Credential 配置。需在 node.json 中定义 credentials 字段，并在代码中通过 this.getCredentials() 获取。
测试与调试使用 n8n 提供的 CLI 工具 n8n-node-dev 进行本地加载和测试。开发时需将节点目录软链接到 ~/.n8n/custom 目录或通过 --load-custom 路径加载。
打包与发布将节点打包为 npm 包，通过 package.json 声明 n8n 节点入口。包名建议以 n8n-nodes- 开头；发布后可通过 n8n 安装插件方式集成。

2.4 节点参数配置通用规则

参数类型说明示例 / 配置方式注意事项
固定值（Fixed Value）直接输入静态文本、数字或布尔值。Field: username → Value: "admin"适用于不变的配置项；不支持动态数据。
表达式（Expression）使用 {{ }} 语法引用其他节点输出或系统变量。{{node["HTTP Request"].json["id"]}} 或 {{$today}}表达式需在参数旁点击 ”{}” 切换模式；错误语法会导致执行失败。
参数引用（$parameter）在 Function/Code 节点中访问当前节点的配置参数。const apiKey = $parameter.apiKey;仅在节点内部脚本中有效；参数名需与 node.json 定义一致。
凭据选择（Credentials）下拉选择已配置的认证信息，自动注入密钥。选择 “Google Sheets Account” 凭据凭据需提前在 Credentials 页面创建；节点会自动加密传输。
模式切换（Mode Toggle）部分节点支持多模式（如 Set 节点有 manual / auto map）。Set 节点：Manual 模式手动设字段；Auto 模式从样本数据映射。不同模式下参数结构不同，切换时可能清空已有配置。
批量输入（List Parameters）支持添加多个同类项（如 Headers、Query Parameters）。添加 Header: Key=Authorization, Value=Bearer xxx每项为键值对；部分服务对大小写敏感（如 Content-Type）。

第三章：数据处理与表达式

3.1 数据结构与 JSON 格式在 n8n 中的表示

概念名称说明注意事项
Itemn8n 中数据的基本单位，是一个包含 json 和 binary 属性的对象。json 属性为普通对象（即业务数据），binary 用于文件等二进制内容。
Items 数组节点输入/输出的数据始终是 Item 对象的数组（即使只有一项）。即使上游只有一个结果，下游仍需通过 items[0] 访问；不可直接当作对象处理。
JSON 结构业务数据以标准 JSON 对象形式存储在 item.json 中。支持嵌套对象和数组，如 {"user": {"name": "Alice", "tags": ["a","b"]}}。
Binary 数据用于传输文件（如图片、PDF），存储在 item.binary 下，按 key 分组。需使用支持 binary 的节点（如 Read Binary Files、Move Binary Data）。
空值处理字段不存在时返回 undefined，不会自动创建路径。使用表达式访问深层字段前应先判断是否存在，避免运行错误。
数据流一致性所有节点必须接收和返回 Items 数组格式，确保工作流链路兼容。自定义 Function 节点若返回非数组结构会导致执行失败。

3.2 表达式语法基础（{{node}}、{{input}}、{{}}）

表达式标识符语法格式用途示例注意事项
{{}}{{ 表达式内容 }}在节点参数中启用动态值计算，支持 JavaScript 表达式子集。{{ "Hello " + $today }}仅在参数输入框点击 ”{}” 后生效；不支持完整 JS（如 for、function）。
{{$input}}{{$input.item.json.field}} 或 {{$input.first()}}引用当前节点的直接输入数据（即上一节点的输出）。{{$input.item.json.email}} 获取当前处理项的 email 字段。$input.item 等价于 items[0]（在单 item 上下文中）；多 item 需遍历。
{{$node}}{{$node["Node Name"].json.field}}引用任意已执行节点的输出数据（按节点名称访问）。{{$node["HTTP Request"].json.id}}被引用节点必须在当前执行路径中已运行；名称需完全匹配（区分大小写）。
{{$workflow}}{{$workflow.id}} 或 {{$workflow.name}}获取当前工作流的元信息。{{$workflow.name}} 返回工作流名称。适用于日志记录或动态路由场景。
{{$execution}}{{$execution.id}}获取当前执行实例的唯一 ID。可用于生成唯一日志标识或调试追踪。执行 ID 在每次运行时唯一。
{{$parameter}}{{$parameter.fieldName}}在 Function/Code 节点内部访问当前节点的参数配置。const url = $parameter.apiUrl;仅在脚本节点中有效；参数名需与 UI 配置一致。

3.3 常用表达式函数（json、item、now、parameter 等）

注：以下函数主要用于 Function/Code 节点内部脚本环境，部分也可在表达式中使用。

函数/变量名语法/类型用途示例注意事项
$json对象（只读）当前 item 的 json 数据的快捷引用，等价于 items[0].json。return { result: $json.value * 2 };仅在单 item 上下文安全；多 item 应使用 items 循环。
$item对象（只读）当前处理的完整 item（含 json 和 binary）。const data = $item.json;同样适用于单 item 场景。
$now字符串返回当前 ISO 8601 时间字符串（UTC）。{{ $now }} → "2025-11-08T10:30:00.000Z"可用于时间戳字段；本地时区需自行转换。
$today字符串返回当前日期（YYYY-MM-DD 格式，基于服务器时区）。{{ $today }} → "2025-11-08"依赖 n8n 服务器系统时区。
$parameter对象访问当前节点在 UI 中配置的参数值。const threshold = $parameter.threshold;参数名必须与 node.json 定义一致。
$runIndex整数当前 item 在批次中的索引（从 0 开始）。用于生成序号：return { index: $runIndex };在 Split In Batches 或多 item 输入时有意义。
$mode字符串返回当前执行模式（"manual" / "production"）。if ($mode === "manual") { ... }可用于区分测试与正式运行逻辑。
$credentials对象访问当前节点绑定的凭据内容（如 apiKey、token）。const token = $credentials.apiKey;凭据需在节点配置中正确关联。

3.4 条件判断与循环处理（IF、Split In Batches、Item Lists）

操作/节点名称操作细节注意事项
IF 节点条件设置在 Parameters 中填写表达式作为判断条件，如 {{$node["Set"].json.score > 80}}。条件为 true 时走第一条输出分支，false 走第二条；支持复杂逻辑（&&、`
多分支处理可串联多个 IF 节点实现 elseif 逻辑，或结合 Switch 节点（社区插件）。原生 n8n 无 Switch 节点，需用多个 IF 模拟。
Split In Batches 节点将大批量 items 分批处理，避免 API 限流或内存溢出。设置 Batch Size（如 10），每批作为一个 item 数组传递给下游。
Item Lists（批量输入）当上游返回多个 items 时，Regular 节点会自动对每个 item 依次执行（隐式循环）。例如 HTTP Request 节点收到 5 个 items，会发起 5 次请求（除非启用”合并”模式）。
手动循环（Function）在 Function 节点中遍历 items 并返回新数组。return items.map(item => ({ json: { doubled: item.json.value * 2 } }));
过滤数据在 Function 节点中使用 .filter() 筛选 items。return items.filter(item => item.json.active === true);
合并结果使用 Merge 节点将多个分支的 items 合并为单一列表。需确保两路输入已完成；选择 Append 模式可简单拼接数组。

第四章：工作流控制与逻辑

4.1 工作流执行流程控制（分支、合并、错误处理）

控制机制说明注意事项
分支（Branching）通过 IF 节点或表达式条件将数据流导向不同路径，实现逻辑分流。IF 节点输出两条连线：true（上）和 false（下）；不可同时走两条路径。
合并（Merging）使用 Merge 节点将两个或多个数据流合并为单一输出流。支持 Append（拼接）、Combine（按索引配对）、Keep Key Match（按字段匹配）三种模式。
并行执行多个节点从同一上游节点分出且无依赖关系时，n8n 会并行处理（若配置允许）。实际是否并行取决于执行器实现；默认本地执行为串行模拟，并行需企业版或自定义配置。
错误传播节点执行失败时，工作流默认中断，后续节点不执行。可通过 Error Trigger 或 Fallback 机制捕获异常，避免整个流程终止。
手动触发测试使用 Manual Trigger 节点可随时启动工作流，用于验证分支逻辑。仅用于开发调试，生产环境应替换为真实 Trigger（如 Webhook、Cron）。
数据路由利用表达式在 Set 或 Function 节点中动态决定下一跳（配合 IF 实现）。n8n 无原生”动态路由”节点，需结合条件判断模拟。

4.2 错误处理机制（Error Trigger、Fallback 节点）

机制名称操作细节注意事项
Error Trigger 节点作为独立工作流的起点，当其他工作流发生未捕获错误时自动触发。需在 Settings → Error Workflow 中指定错误处理工作流；仅捕获未处理的异常。
Fallback 节点n8n 原生不提供名为 “Fallback” 的节点，但可通过以下方式模拟：实际 fallback 逻辑需手动构建，非内置功能。
模拟 Fallback 方法一在关键节点后连接 IF 节点，检查是否存在 error 字段（部分节点返回错误信息）。并非所有节点在失败时返回结构化 error，多数直接抛出异常。
模拟 Fallback 方法二将易错操作封装在子工作流中，主工作流调用 Execute Workflow 节点并处理其输出。子工作流失败不会中断主流程，可在主流程中判断执行状态。
重试机制n8n 本身不支持自动重试，但可通过循环 + 条件判断 + Delay 节点手动实现。需谨慎设计，避免无限循环；建议设置最大重试次数。
错误日志记录在 Error Trigger 工作流中添加 HTTP Request 或 Slack 节点发送告警通知。应包含 {{$error.message}}、{{$workflow.name}}、{{$execution.id}} 等上下文信息。

4.3 调试技巧与执行日志分析

调试方法操作细节注意事项
查看 Execution 日志在 Editor 底部或 Executions 页面点击某次执行，查看每个节点的输入/输出数据。输出数据以 JSON 格式展示，支持展开嵌套对象。
使用 Debug Helper 节点添加 “Debug Helper” 节点（社区插件）或临时连接一个 Set/Function 节点打印数据。官方版本无专用 Debug 节点，常用 Set 节点占位观察输出。
表达式测试在任意参数框中输入 {{ 表达式 }} 并预览结果（鼠标悬停或保存后执行）。复杂表达式建议先在 Function 节点中验证逻辑。
单步执行从 Manual Trigger 开始，逐个节点点击 “Execute Node” 查看中间结果。适用于定位数据变形或丢失问题。
检查错误堆栈节点报错时，点击红色错误提示展开详细信息，包含错误类型和位置。常见错误：字段不存在、凭据缺失、API 限流、表达式语法错误。
清除缓存执行修改节点逻辑后，务必重新执行整个工作流，避免旧缓存干扰判断。n8n 不自动刷新历史执行数据，调试时应关注最新一次运行。

4.4 工作流版本管理与环境迁移

操作名称操作细节注意事项
导出工作流在 Workflow 列表页点击 “Export”，下载 .json 文件。导出文件包含节点配置、连接关系，但不包含 Credentials（出于安全考虑）。
导入工作流在目标环境点击 “Import”，上传 .json 文件即可还原工作流。若引用的 Credentials 名称不存在，需手动重新绑定。
凭据迁移凭据需单独导出（通过数据库或 API），或在新环境中重新创建。n8n 不支持凭据随工作流一键导出，防止密钥泄露。
使用环境变量将敏感配置（如 API 地址、密钥）通过 {{$envVar('VAR_NAME')}} 引用。需在启动 n8n 时传入环境变量（如 -e VAR_NAME=value）。
Git 版本控制将导出的 .json 工作流文件纳入 Git 仓库，实现变更追踪与协作。建议为每个工作流单独建文件，并规范命名（如 send-slack-alert.json）。
多环境部署策略开发（dev）、测试（staging）、生产（prod）环境分别部署独立 n8n 实例。通过统一命名规范和凭据模板，降低跨环境配置差异。
自动化部署（CI/CD）编写脚本调用 n8n CLI 或 REST API 批量导入工作流（需启用 Public API）。需开启 N8N_PUBLIC_API_ENABLED=true 并配置 API 认证。

第五章：集成与扩展

5.1 与外部服务集成（Slack、Google Sheets、Notion 等）

服务名称用途配置要点注意事项
Slack发送消息、创建频道、获取用户信息等。创建 Slack App，启用 Bot Token，授予 chat:write 等权限；在 n8n 中新建 Slack 凭据。消息内容支持 blocks 和 attachments；需确保机器人被邀请到目标频道。
Google Sheets读取/写入电子表格数据，追加行、查询范围等。使用 OAuth2 授权；首次需登录 Google 账号授权；选择 Spreadsheet ID 和 Range。Spreadsheet ID 来自 URL；写入时需匹配列数；频繁操作可能触发配额限制。
Notion创建页面、更新数据库条目、搜索内容等。在 Notion 中创建 Integration，获取 Internal Integration Token；共享数据库给该集成。Notion API 仅支持数据库和页面操作；不支持 block 追加（需用 Append Block 节点）。
Gmail发送邮件、读取收件箱、标记邮件等。启用 Gmail API，OAuth2 授权；凭据中选择邮箱地址。发送 HTML 邮件需设置 contentType 为 html；附件需通过 binary 数据传入。
Airtable操作 Base 中的记录（增删改查）、列出表结构。获取 API Key 和 Base ID；在节点参数中指定 Table Name。Base ID 格式为 appxxxxxxxx；字段名区分大小写，建议使用 Field ID。
Discord发送消息到频道、获取服务器信息。创建 Bot，复制 Token；在 Webhook URL 或 Bot 模式下使用。推荐使用 Webhook URL 方式（无需复杂权限）；Bot 模式需邀请到服务器。
Microsoft Teams通过 Incoming Webhook 发送通知卡片。在 Teams 频道中创建连接器，获取 Webhook URL；在 HTTP Request 节点中 POST JSON。n8n 无原生 Teams 节点，通常用 HTTP Request + Adaptive Card 模板实现。

5.2 使用 Webhook 接收和响应外部请求

操作要素说明示例 / 配置方式注意事项
Webhook 节点创建在工作流中添加 “Webhook” 节点，自动分配唯一 URL。Method: POST；Path: /order-notify；Response Mode: On ReceivedURL 格式：https://your-n8n.com/webhook/xxxxx/order-notify
响应模式（Response Mode）决定何时返回 HTTP 响应给调用方。On Received：立即返回 200；Last Node：等待整个工作流执行完再响应。若外部系统要求即时 ACK，选 On Received；若需返回处理结果，选 Last Node。
自定义响应体在 Webhook 节点下方连接 Set 或 Function 节点构造响应内容。Set 节点设字段：body = "OK"，headers = {"Content-Type": "text/plain"}仅当 Response Mode = Last Node 时生效；响应体必须由最后一个节点输出。
验证请求来源使用表达式检查 headers 或 query 参数中的 token。条件：{{$input.headers["x-secret"] === "mytoken"}} → 连接 IF 节点过滤非法请求。建议始终验证来源，防止未授权调用。
处理 JSON Body外部 POST 的 JSON 自动解析为 {{$input.json}}。{{$input.json.orderId}} 可直接用于后续节点。Content-Type 必须为 application/json，否则按文本处理。
支持 CORS默认 Webhook 节点不启用 CORS；如需浏览器直接调用，需反向代理配置。在 Nginx 或 Cloudflare 中添加 Access-Control-Allow-Origin 头。n8n 本身不提供 CORS 配置选项。

5.3 编写自定义函数节点（Function / Code 节点）

要素名称语法/结构用途示例注意事项
items数组，每个元素为 { json: {...}, binary?: {...} }访问上游所有输入数据项。return items.map(item => ({ json: { doubled: item.json.value * 2 } }));必须返回相同结构的数组。
$input对象，提供 first(), last(), all(), item 等方法快捷访问输入数据（常用于单 item 场景）。const email = $input.item.json.email;$input.item 等价于 items[0]。
$json对象（仅在单 item 上下文安全）当前 item.json 的别名。return { result: $json.score > 60 ? "Pass" : "Fail" };多 item 输入时行为未定义，应避免使用。
返回格式必须为 INodeExecutionData[] 类型，即 { json: object, binary?: object }[]确保下游节点能正确解析输出。return [{ json: { message: "Hello" } }];即使只返回一项，也必须包裹在数组中。
异步支持在 Function 节点设置中启用 “Execute Once” 和 “Async”（v1.0+）允许使用 await 调用外部 API。const res = await fetch(url); return [{ json: await res.json() }];需显式启用 async 模式；否则 await 会报错。
错误抛出throw new Error("Custom message")主动中断工作流并记录错误。if (!data) throw new Error("Missing input");错误会被全局错误处理机制捕获（如 Error Trigger）。

5.4 开发与部署自定义节点（Node Package）

开发要素说明示例 / 结构注意事项
项目初始化使用 n8n 官方脚手架：npx create-n8n-node@latest生成目录包含 package.json、nodes/、credentials/、dist/ 等。需安装 Node.js ≥18；脚手架自动配置 TypeScript 和构建脚本。
node.json节点元数据文件，定义参数、图标、输入输出等。{ "displayName": "My Node", "name": "myNode", "group": ["transform"], "version": 1, "defaults": { "name": "My Node" }, "inputs": ["main"], "outputs": ["main"], "properties": [...] }name 必须唯一；properties 定义 UI 参数（如 string、options、collection）。
execute() 方法节点核心逻辑，位于 .ts 文件中，返回 Promise<INodeExecutionData[][]>。async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> { ... }使用 this.getInputData() 获取输入；this.getNodeParameter() 获取参数。
凭据声明在 credentials/ 目录定义凭据类型，在 node.json 中引用。credentials: [{ name: "myServiceApi", required: true }]凭据值通过 this.getCredentials('myServiceApi') 获取。
本地测试运行 npm run build && n8n start --load-custom [路径]或使用 n8n-node-dev 工具：n8n-node-dev --install --watch开发时建议启用 --watch 自动重载。
打包发布执行 npm publish，包名建议为 n8n-nodes-[service]package.json 中需包含 n8n 字段：{ "n8n": { "nodes": ["dist/nodes/MyNode/MyNode.node.js"] } }用户通过 npm install 安装后，重启 n8n 即可使用。
部署到生产环境在生产实例执行 npm install your-node-package，然后重启 n8n 服务。若使用 Docker，需将包加入 Dockerfile 并 rebuild 镜像。确保依赖版本兼容 n8n 运行时；避免使用实验性 API。

第六章：部署与运维

6.1 本地部署（npm / Docker）

部署方式操作细节注意事项
npm 全局安装执行 npm install n8n -g，然后运行 n8n start 启动服务。需 Node.js ≥18；适用于快速测试，不推荐生产环境。
项目级安装在项目目录执行 npm init -y && npm install n8n，通过 npx n8n start 启动。便于版本锁定（package.json 中指定 n8n 版本）。
Docker 运行执行 docker run -it --rm -p 5678:5678 n8nio/n8n默认数据存储在容器内，重启后丢失；需挂载卷持久化。
持久化数据添加 -v ~/.n8n:/home/node/.n8n 挂载配置与数据库目录。SQLite 数据库和凭据密钥均保存在此目录；备份此目录即可迁移实例。
自定义端口通过 -e PORT=8080 或命令行参数 --port 8080 修改监听端口。若与宿主机其他服务冲突，必须修改。
后台运行使用 docker run -d（detached 模式）或 pm2 管理 npm 进程。生产环境建议配合 systemd 或 Docker Compose 实现自启。

6.2 云部署方案（n8n.cloud、自建服务器）

方案类型操作细节注意事项
n8n.cloud访问 https://n8n.cloud，注册账号，创建实例，选择套餐（免费/付费）。免运维、自动更新；但无法安装自定义节点；高级功能需订阅。
自建云服务器在 AWS EC2、阿里云 ECS 等部署 Docker 或 npm 版本 n8n。需自行配置防火墙、域名、SSL 证书；建议使用 Ubuntu/CentOS 最新 LTS。
反向代理（Nginx）配置 Nginx 将域名（如 n8n.example.com）代理到本地 5678 端口。启用 HTTPS（Let’s Encrypt）；设置 X-Forwarded-* 头确保 Webhook 正常工作。
域名与 HTTPS使用 Certbot 获取免费 SSL 证书，强制重定向 HTTP → HTTPS。Webhook URL 必须为 HTTPS（多数第三方服务要求）；否则可能被拒绝。
容器编排（K8s）编写 Kubernetes Deployment + Service + Ingress，挂载 PVC 存储数据。适用于大规模高可用场景；需管理 PostgreSQL 替代默认 SQLite。
成本对比n8n.cloud 月费约 $20 起；自建最低配置云服务器约 $5/月（但需运维投入）。小团队可选 n8n.cloud；企业级建议自建以控制数据与扩展性。

6.3 安全配置（用户认证、Webhook 验证、加密凭据）

安全措施配置方式注意事项
基本身份认证设置环境变量：N8N_BASIC_AUTH_USER=admin 和 N8N_BASIC_AUTH_PASSWORD=xxx登录界面将启用用户名/密码；密码建议使用强密码并定期更换。
用户系统（企业版）n8n 企业版支持多用户、RBAC 权限控制。社区版仅支持单用户或无认证（公开访问风险高）。
Webhook 请求验证在 Webhook 节点后接 IF 节点，检查 header 或 query 中的 secret token。示例：{{$input.headers["x-signature"] === "my-secret"}}；避免未授权触发。
凭据加密n8n 默认使用 AES 加密凭据并存入数据库；需设置 N8N_ENCRYPTION_KEY。若未设置，每次启动会生成临时密钥，导致凭据无法解密；务必固定密钥！
禁用公开注册社区版本身无用户注册功能，但若暴露 Editor 页面，等同于开放自动化权限。强烈建议启用 Basic Auth 或放在内网/VPC 中。
API 访问控制如启用 Public API（N8N_PUBLIC_API_ENABLED=true），必须设置 API Key。通过 N8N_PUBLIC_API_SECRET 配置密钥；调用时需在 Header 中携带。

6.4 性能调优与监控

调优方向操作细节注意事项
数据库存储默认使用 SQLite；高并发场景建议切换为 PostgreSQL。通过 DB_TYPE=postgres 及相关连接参数配置；提升并发写入性能。
执行队列控制设置 N8N_CONCURRENCY 限制同时运行的工作流数量（默认无限制）。防止资源耗尽；例如设为 5 可避免大量 Webhook 同时触发压垮服务。
日志级别通过 `N8N_LOG_LEVEL=infodebug
监控集成通过 Prometheus exporter（需插件或企业版）暴露指标，接入 Grafana。社区版无内置监控；可自行在关键节点记录执行时间到外部日志系统。
内存优化避免在 Function 节点加载大文件；使用 Split In Batches 分批处理大数据集。单次处理超过 1000 items 可能导致内存溢出。
缓存策略对频繁调用的只读 API（如用户信息查询），可在上游加 Set 节点缓存结果。n8n 无原生缓存机制；需结合外部 Redis 或利用工作流状态模拟。

第七章：高级主题

7.1 多环境配置（开发/测试/生产）

环境管理要素操作细节注意事项
环境隔离为 dev/staging/prod 分别部署独立 n8n 实例（不同服务器或命名空间）。避免测试流程误操作生产数据。
配置参数化使用环境变量注入差异配置（如 API 地址、数据库名）。在节点中通过 {{$envVar('API_URL')}} 引用；需启动时传入变量。
凭据命名规范所有环境使用相同凭据名称（如 “Slack_Prod”），但内容不同。导入工作流后只需重新绑定凭据，无需修改节点逻辑。
工作流导出/导入开发完成后导出 .json，在测试/生产环境导入。确保目标环境已安装相同自定义节点版本。
GitOps 流程将工作流 JSON 文件纳入 Git 仓库，通过 CI/CD 自动部署到各环境。可结合 GitHub Actions + n8n Public API 实现自动化同步。
禁用生产手动触发在生产环境移除 Manual Trigger 节点，或通过权限控制禁止编辑。防止人为误触发关键流程。

7.2 工作流复用与子工作流（Execute Workflow 节点）

复用机制操作细节注意事项
Execute Workflow 节点在主工作流中添加该节点，选择目标子工作流，传递输入数据。子工作流必须存在且已激活（或至少已保存）。
参数传递主工作流的输出自动作为子工作流的输入（items 数组）。子工作流可通过 {{$input}} 或 {{$node["Parent"].json}} 访问数据。
返回值接收子工作流的最终输出会作为 Execute Workflow 节点的输出，供后续节点使用。可用于封装通用逻辑（如”发送通知模板”、“数据清洗”）。
错误隔离子工作流失败不会中断主工作流（除非主流程未处理错误）。建议在主流程中检查子工作流执行状态（通过 error 字段或 IF 判断）。
循环调用可在 Function 节点中动态构造多个调用参数，配合 Item Lists 实现批量子流程。注意并发限制；避免递归调用导致栈溢出。
版本依赖子工作流更新后，所有调用方自动使用新版本。需确保接口兼容性；重大变更应新建版本工作流（如 “Notify_v2”）。

7.3 并行执行与限流控制

控制机制说明注意事项
隐式并行当一个节点输出多个 items，且下游为 Regular 节点时，n8n 默认逐个处理。实际为串行模拟；并非真正并发执行。
真正并行（企业版）n8n 企业版支持 Queue Mode + Redis，实现多 worker 并行执行不同工作流。社区版无法实现跨工作流并行；同一工作流始终串行。
限流（Rate Limit）在 HTTP Request 节点中设置 “Requests per second” 或使用 Delay 节点。防止触发第三方 API 限流（如 Twitter 300/15min）。
Split In Batches将 1000 个 items 拆分为每批 10 个，逐批处理。每批作为一个 item 数组传递；适合分页 API 或批量写入。
Delay 节点在循环或批量操作中插入延迟（如每项间隔 1 秒）。可缓解服务器压力；但会显著延长总执行时间。
手动并发模拟创建多个独立工作流，由外部调度器（如 Cron）分别触发。适用于完全独立的任务；无法共享中间状态。

7.4 社区资源与插件生态

资源类型说明获取方式 / 链接
官方文档包含安装指南、节点参考、表达式语法、API 文档等。https://docs.n8n.io
工作流模板库官方提供数百个预设模板（如 Shopify + Slack 通知、Airtable 同步等）。Editor 中点击 “Templates” 标签页；或访问 https://n8n.io/workflows
GitHub 仓库核心代码、Issue 跟踪、贡献指南。https://github.com/n8n-io/n8n
社区论坛用户问答、经验分享、插件推荐。https://community.n8n.io
自定义节点仓库社区开发的扩展节点（如 Telegram Bot、Redis、MongoDB 等）。npm 搜索 n8n-nodes-*；或浏览 GitHub Topics: n8n-node
插件市场（企业版）企业版提供官方认证插件，支持更深度集成。需订阅 n8n Enterprise Plan
YouTube 教程官方及社区制作的视频教程，涵盖从入门到高级场景。搜索 “n8n tutorial”
Discord 社群实时交流、快速答疑。链接见官网 footer