name: n8n description: n8n 工作流自动化模式与 API 集成。此技能应用于创建 n8n 工作流、使用 Webhook、通过 REST API 管理工作流或将 n8n 与 MCP 服务器集成。涵盖工作流 JSON 结构、节点模式和自动化最佳实践。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

n8n 工作流自动化技能

此技能支持为自动化任务创建和管理 n8n 工作流。

先决条件

运行中的 n8n 实例并具有 API 访问权限：

N8N_HOST=localhost
N8N_PORT=5678
N8N_API_KEY=your-api-key

核心概念

工作流结构

每个 n8n 工作流都是具有以下结构的 JSON：

{
  "name": "工作流名称",
  "nodes": [],
  "connections": {},
  "settings": {
    "executionOrder": "v1"
  }
}

节点结构

每个节点包含：

{
  "id": "唯一标识符",
  "name": "显示名称",
  "type": "n8n-nodes-base.节点类型",
  "typeVersion": 1,
  "position": [x, y],
  "parameters": {},
  "credentials": {}
}

连接结构

连接定义了节点之间的数据流：

{
  "源节点": {
    "main": [
      [{"node": "目标节点", "type": "main", "index": 0}]
    ]
  }
}

常见工作流模式

1. Webhook 触发的工作流

创建一个触发工作流执行的 HTTP 端点：

{
  "name": "Webhook 处理器",
  "nodes": [
    {
      "id": "webhook",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [250, 300],
      "webhookId": "my-webhook",
      "parameters": {
        "path": "my-endpoint",
        "httpMethod": "POST",
        "responseMode": "responseNode"
      }
    },
    {
      "id": "respond",
      "name": "响应",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.1,
      "position": [450, 300],
      "parameters": {
        "respondWith": "json",
        "responseBody": "={{ $json }}"
      }
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{"node": "Respond", "type": "main", "index": 0}]]
    }
  }
}

访问地址：http://localhost:5678/webhook/my-endpoint

2. HTTP 请求模式

进行外部 API 调用：

{
  "id": "http",
  "name": "HTTP 请求",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4.2,
  "position": [450, 300],
  "parameters": {
    "method": "POST",
    "url": "https://api.example.com/endpoint",
    "authentication": "predefinedCredentialType",
    "nodeCredentialType": "myApiCredential",
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={{ JSON.stringify($json) }}"
  },
  "credentials": {
    "myApiCredential": {"id": "cred-id", "name": "我的凭证"}
  }
}

3. 条件分支（IF 节点）

根据条件路由数据：

{
  "id": "if",
  "name": "IF",
  "type": "n8n-nodes-base.if",
  "typeVersion": 2,
  "position": [450, 300],
  "parameters": {
    "conditions": {
      "options": {
        "caseSensitive": true,
        "leftValue": "",
        "typeValidation": "strict"
      },
      "conditions": [
        {
          "leftValue": "={{ $json.status }}",
          "rightValue": "success",
          "operator": {
            "type": "string",
            "operation": "equals"
          }
        }
      ],
      "combinator": "and"
    }
  }
}

4. 循环处理项目（SplitInBatches）

分批处理项目：

{
  "id": "batch",
  "name": "循环处理项目",
  "type": "n8n-nodes-base.splitInBatches",
  "typeVersion": 3,
  "position": [450, 300],
  "parameters": {
    "batchSize": 10,
    "options": {}
  }
}

n8n REST API

列出工作流

curl -s "http://localhost:5678/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

获取工作流

curl -s "http://localhost:5678/api/v1/workflows/{id}" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

创建工作流

curl -s -X POST "http://localhost:5678/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "新工作流", "nodes": [...], "connections": {...}}'

更新工作流

curl -s -X PUT "http://localhost:5678/api/v1/workflows/{id}" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "已更新", "nodes": [...], "connections": {...}}'

激活/停用

curl -s -X POST "http://localhost:5678/api/v1/workflows/{id}/activate" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

curl -s -X POST "http://localhost:5678/api/v1/workflows/{id}/deactivate" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

获取执行记录

curl -s "http://localhost:5678/api/v1/executions?workflowId={id}&limit=10&includeData=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

表达式语法

n8n 使用表达式处理动态值：

语法	描述
`={{ $json.field }}`	访问当前项目字段
`={{ $json.body.param }}`	访问嵌套字段
`={{ $('节点名称').item.json.field }}`	访问特定节点的输出
`={{ $input.first().json }}`	第一个输入项
`={{ $input.all() }}`	所有输入项
`={{ JSON.stringify($json) }}`	转换为 JSON 字符串

常见节点类型

节点	类型	用途
Webhook	`n8n-nodes-base.webhook`	HTTP 触发器
HTTP 请求	`n8n-nodes-base.httpRequest`	API 调用
响应 Webhook	`n8n-nodes-base.respondToWebhook`	返回 HTTP 响应
IF	`n8n-nodes-base.if`	条件分支
Switch	`n8n-nodes-base.switch`	多路分支
Set	`n8n-nodes-base.set`	转换数据
Code	`n8n-nodes-base.code`	自定义 JavaScript
Split In Batches	`n8n-nodes-base.splitInBatches`	循环处理
Merge	`n8n-nodes-base.merge`	合并分支

MCP 集成

n8n 可以通过内置的 MCP 服务器将工作流作为 MCP 工具公开：

在工作流设置中启用 MCP："availableInMCP": true
访问 MCP 端点：http://localhost:5678/mcp-server/http
使用 supergateway 进行 Claude Code 集成

提示

Webhook 响应：使用 responseMode: "responseNode" 配合 Respond 节点以获得控制权
凭证：将 API 密钥存储在 n8n 凭证中，通过 ID 引用
错误处理：添加 Error Trigger 节点用于失败通知
测试：在开发过程中使用 /webhook-test/ 路径
ADF 格式：Jira/Confluence 需要 Atlassian Document Format 来处理富文本