n8n

N8N 技能

基于官方文档生成的 n8n 开发全面指南。n8n 是一种采用 fair-code 许可证的工作流自动化工具，结合了 AI 能力与业务流程自动化。

何时使用此技能

遇到以下情况时，应使用此技能：

• 构建或调试 n8n 工作流
• 使用 Code 节点（JavaScript 或 Python）
• 使用表达式和数据转换
• 实现 AI Agent、链或 RAG 工作流
• 配置 n8n 部署（Docker、npm、可自托管）
• 设置 Webhook、凭据或集成
• 处理工作流中的错误
• 使用队列模式扩展 n8n
• 创建自定义节点或为 n8n 添加白标
• 以编程方式使用 n8n API
• 在 n8n 中使用 LangChain
• 迁移到 n8n v1.0

核心概念

核心组件

• 工作流：由节点连接组成的可视化自动化流程
• 节点：工作流中的单项操作（触发器、操作、逻辑等）
• 表达式：使用 {{ }} 语法访问和转换数据的代码片段
• 凭据：用于安全存储 API 密钥和身份验证信息
• 执行：单次工作流运行及其数据和状态

数据结构

• n8n 在节点之间传递的数据为 items（JSON 对象数组）
• 每个 item 都有一个包含主要数据的 json 属性
• 二进制数据单独存储在 binary 属性中
• 在表达式中使用 $json 访问当前 item 的数据

AI 能力

• Agent：能够使用工具并做出决策的 AI
• 链：预定义的 AI 操作序列
• 记忆：存储对话历史以提供上下文
• 工具：AI Agent 可以调用的函数
• 向量数据库：存储和检索用于 RAG 的嵌入

快速参考

示例 1：用于访问数据的基本表达式

// Access data from the current item
{{ $json.name }}

// Access data from a specific node
{{ $node["HTTP Request"].json.response }}

// Access all items from a node
{{ $("HTTP Request").all() }}

示例 2：带身份验证的 HTTP Request

使用 HTTP Request 节点时，请处理错误和速率限制：

// In HTTP Request node settings:
// - Enable "Retry on Fail"
// - Set Max Tries to 3
// - Set Wait Between Tries (ms) to 1000

// For rate limiting, use Batching:
// - Items per Batch: 10
// - Batch Interval (ms): 1000

示例 3：Code 节点——转换数据（JavaScript）

// Access input data
const items = $input.all();

// Transform each item
return items.map(item => {
  return {
    json: {
      fullName: `${item.json.firstName} ${item.json.lastName}`,
      email: item.json.email.toLowerCase(),
      timestamp: new Date().toISOString()
    }
  };
});

示例 4：Code 节点——筛选数据（Python）

# Filter items based on a condition
output = []

for item in items:
    if item['json']['status'] == 'active':
        output.append({
            'json': {
                'id': item['json']['id'],
                'name': item['json']['name']
            }
        })

return output

示例 5：表达式——使用 Luxon 处理日期

// Current date
{{ $now }}

// Format date
{{ $now.toFormat('yyyy-MM-dd') }}

// Add 7 days
{{ $now.plus({ days: 7 }) }}

// Parse and format custom date
{{ DateTime.fromISO($json.dateString).toFormat('LLL dd, yyyy') }}

示例 6：JWT 身份验证凭据

对于需要 JWT 身份验证的 API：

// Use JWT credential with:
// - Key Type: Passphrase (for HMAC) or PEM Key (for RSA/ECDSA)
// - Secret: Your secret key
// - Algorithm: HS256, RS256, ES256, etc.

// The JWT credential automatically generates tokens
// Use it in HTTP Request node > Authentication > JWT

示例 7：处理工作流中的错误

// In Code node, use try-catch:
try {
  const result = $json.data.someField.toUpperCase();
  return [{ json: { result } }];
} catch (error) {
  // Return error information
  return [{
    json: {
      error: error.message,
      originalData: $json
    }
  }];
}

// Or set up Error Workflow in Workflow Settings
// to catch all failures and send notifications

示例 8：HTTP Request 中的分页

// Use pagination to fetch all pages
// In HTTP Request node > Pagination:

// Type: Generic Pagination
// Request URL: {{ $url }}&page={{ $pageNumber }}
// Complete When: {{ $response.body.hasMore === false }}
// Next Page URL: Automatic

示例 9：使用工具的 AI Agent

// In AI Agent node:
// 1. Connect a Chat Model (OpenAI, etc.)
// 2. Add tools (Calculator, HTTP Request, etc.)
// 3. Configure memory if needed

// The agent can:
// - Analyze user input
// - Decide which tools to use
// - Execute tools and process results
// - Return final answer

示例 10：环境变量和静态数据

// Access environment variables
{{ $env.MY_API_KEY }}

// Store workflow static data (persists across executions)
const staticData = getWorkflowStaticData('global');
staticData.lastRun = new Date().toISOString();
staticData.counter = (staticData.counter || 0) + 1;

// Retrieve static data
{{ $workflow.staticData.counter }}

参考文件

此技能包含 references/ 中的完整文档：

• llms-txt.md - 为大模型整理的完整 n8n 文档

  • 安装和设置指南
  • 节点参考文档
  • API 文档
  • 代码示例和模式
  • 配置选项
  • 故障排除指南

• llms-full.md - 包含深入技术细节的扩展文档

  • 高级配置
  • 扩展和性能
  • 安全和身份验证
  • 自定义节点开发
  • 白标和嵌入选项

需要详细信息时，使用 view 查看特定参考文件。

使用此技能

新手入门

1. 从创建基本工作流开始：

   • 触发节点（Webhook、Schedule、Manual）
   • 操作节点（HTTP Request、Set、Edit Fields）
   • 通过简单的 {{ $json.field }} 访问方式学习表达式语法

2. 理解数据结构：

   • 每个节点都会输出一个 items 数组
   • 使用数据检查器查看 item 结构
   • 使用 Edit Fields 节点练习数据转换

3. 常见模式：

   • Webhook → HTTP Request → Set → Respond to Webhook
   • Schedule → Code → HTTP Request → Conditional
   • Manual → Loop Over Items → Process Each

中级用户

1. 掌握 Code 节点：

   • 使用 JavaScript 模式进行复杂转换
   • 使用 $input.all() 访问所有项
   • 返回带有 json 属性且格式正确的项

2. 使用表达式：

   • 使用内置方法：.first()、.last()、.item
   • 使用 Luxon 操作日期
   • 使用 JMESPath 查询复杂 JSON

3. 错误处理：

   • 在 Code 节点中使用 Try-Catch
   • 设置错误工作流
   • 为 API 调用配置失败后重试

4. 数据操作：

   • 合并来自多个来源的数据
   • 拆分和筛选项
   • 循环处理各项以进行批量处理

高级用户

1. AI 和 LangChain：

   • 使用自定义工具构建 AI Agent
   • 使用向量数据库实现 RAG
   • 在对话工作流中使用记忆
   • 串联多个 AI 操作

2. 扩展和性能：

   • 配置队列模式以进行分布式执行
   • 优化数据库设置
   • 使用执行数据清理
   • 配置任务运行器

3. 自定义开发：

   • 创建自定义节点
   • 为嵌入式使用打造白标 n8n
   • 使用 n8n API 管理工作流
   • 使用 AWS/Azure/GCP 实现外部密钥管理

4. 高级模式：

   • 使用子工作流实现复用
   • Webhook 身份验证和验证
   • 使用 JMESPath 进行复杂数据转换
   • 使用 SSE/WebSockets 实时处理数据

常见问题和解决方案

HTTP 请求错误

• 400 Bad Request：检查查询参数和数组格式
• 403 Forbidden：验证凭据和 API 权限
• 429 Rate Limit：使用批处理或失败后重试选项
• 404 Not Found：确认端点 URL 正确

表达式错误

• v1.0+ 中，工作流遇到表达式错误时会失败
• 设置错误工作流以捕获失败
• 在表达式编辑器中测试表达式
• 访问属性前，检查值是否未定义

数据类型问题

• 使用 .toString()、.toNumber() 转换类型
• 使用 {{ $json.field || 'default' }} 处理 null/undefined
• 二进制数据需要使用缓冲区进行特殊处理

迁移到 v1.0

• 新的执行顺序（深度优先，而非广度优先）
• Code 节点支持 Python（Pyodide）
• 必须进行用户管理（不再支持 BasicAuth）
• WebSocket 推送后端现已设为默认值
• 需要 Node 18.17.0 或更高版本

环境配置

Docker 设置

# Basic n8n with Docker
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

# With environment variables
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=password \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

关键环境变量

• N8N_HOST：主机名（默认值：localhost）
• N8N_PORT：端口（默认值：5678）
• N8N_PROTOCOL：http 或 https
• WEBHOOK_URL：外部 webhook URL
• N8N_ENCRYPTION_KEY：凭据加密密钥
• DB_TYPE：数据库类型（sqlite、postgres）
• EXECUTIONS_MODE：queue 或 main（扩展时使用 queue）

资源

官方资源

• n8n 文档
• n8n 社区论坛
• n8n 工作流模板
• n8n GitHub 仓库

学习路径

• 一级课程：构建基础工作流
• 二级课程：高级数据处理和错误管理
• 视频课程：可视化学习资源
• AI 教程：从头开始构建 AI 工作流

API 和开发

• API 参考
• 创建自定义节点
• 节点开发

说明

• 此技能根据 n8n 官方文档自动生成
• 代码示例使用适当的语言标签进行语法高亮
• 示例摘自文档中的真实应用模式
• 聚焦于可立即使用的实用、可执行模式

更新

要使用更新后的文档刷新此技能：

1. 使用相同配置重新运行抓取工具
2. 技能将使用最新信息重新构建
3. 查看快速参考部分，了解新增示例