n8n-expression-syntax

n8n 表达式语法

在工作流中编写正确 n8n 表达式的专家指南。

---

表达式格式

n8n 中的所有动态内容都使用双大括号：

{{expression}}

示例：

✅ {{$json.email}}
✅ {{$json.body.name}}
✅ {{$node["HTTP Request"].json.data}}
❌ $json.email  (no braces - treated as literal text)
❌ {$json.email}  (single braces - invalid)

---

核心变量

$json - 当前节点输出

访问当前节点的数据：

{{$json.fieldName}}
{{$json['field with spaces']}}
{{$json.nested.property}}
{{$json.items[0].name}}

$node - 引用其他节点

访问任意前序节点的数据：

{{$node["Node Name"].json.fieldName}}
{{$node["HTTP Request"].json.data}}
{{$node["Webhook"].json.body.email}}

重要：

• 节点名称必须使用引号
• 节点名称区分大小写
• 必须与工作流中的节点名称完全一致

$now - 当前时间戳

访问当前日期/时间：

{{$now}}
{{$now.toFormat('yyyy-MM-dd')}}
{{$now.toFormat('HH:mm:ss')}}
{{$now.plus({days: 7})}}

$env - 环境变量

访问环境变量：

{{$env.API_KEY}}
{{$env.DATABASE_URL}}

---

🚨 关键：Webhook 数据结构

最常见的错误：Webhook 数据不在根级别！

Webhook 节点输出结构

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // ⚠️ USER DATA IS HERE!
    "name": "John",
    "email": "[email protected]",
    "message": "Hello"
  }
}

正确访问 Webhook 数据

❌ WRONG: {{$json.name}}
❌ WRONG: {{$json.email}}

✅ CORRECT: {{$json.body.name}}
✅ CORRECT: {{$json.body.email}}
✅ CORRECT: {{$json.body.message}}

原因：Webhook 节点会将传入数据封装在 .body 属性下，以保留标头、参数和查询参数。

---

常见模式

访问嵌套字段

// Simple nesting
{{$json.user.email}}

// Array access
{{$json.data[0].name}}
{{$json.items[0].id}}

// Bracket notation for spaces
{{$json['field name']}}
{{$json['user data']['first name']}}

引用其他节点

// Node without spaces
{{$node["Set"].json.value}}

// Node with spaces (common!)
{{$node["HTTP Request"].json.data}}
{{$node["Respond to Webhook"].json.message}}

// Webhook node
{{$node["Webhook"].json.body.email}}

组合变量

// Concatenation (automatic)
Hello {{$json.body.name}}!

// In URLs
https://api.example.com/users/{{$json.body.user_id}}

// In object properties
{
  "name": "={{$json.body.name}}",
  "email": "={{$json.body.email}}"
}

---

不应使用表达式的场景

❌ Code 节点

Code 节点使用直接 JavaScript 访问方式，而非表达式！

// ❌ WRONG in Code node
const email = '={{$json.email}}';
const name = '{{$json.body.name}}';

// ✅ CORRECT in Code node
const email = $json.email;
const name = $json.body.name;

// Or using Code node API
const email = $input.item.json.email;
const allItems = $input.all();

❌ Webhook 路径

// ❌ WRONG
path: "{{$json.user_id}}/webhook"

// ✅ CORRECT
path: "user-webhook"  // Static paths only

❌ 凭据字段

// ❌ WRONG
apiKey: "={{$env.API_KEY}}"

// ✅ CORRECT
Use n8n credential system, not expressions

---

验证规则

1. 始终使用 {{}}

表达式必须用双大括号括起来。

❌ $json.field
✅ {{$json.field}}

2. 名称含空格时使用引号

包含空格的字段或节点名称需要使用方括号表示法：

❌ {{$json.field name}}
✅ {{$json['field name']}}

❌ {{$node.HTTP Request.json}}
✅ {{$node["HTTP Request"].json}}

3. 与节点名称完全匹配

节点引用区分大小写：

❌ {{$node["http request"].json}}  // lowercase
❌ {{$node["Http Request"].json}}  // wrong case
✅ {{$node["HTTP Request"].json}}  // exact match

4. 不要嵌套 {{}}

不要重复用大括号包裹表达式：

❌ {{{$json.field}}}
✅ {{$json.field}}

---

常见错误

如需查看完整的错误目录及修复方法，请参阅 COMMON_MISTAKES.md

快速修复

错误	修复
$json.field	{{$json.field}}
{{$json.field name}}	{{$json['field name']}}
{{$node.HTTP Request}}	{{$node["HTTP Request"]}}
{{{$json.field}}}	{{$json.field}}
{{$json.name}}（webhook）	{{$json.body.name}}
'={{$json.email}}'（Code 节点）	$json.email

---

实用示例

如需查看真实工作流示例，请参阅 EXAMPLES.md

示例 1：Webhook 到 Slack

Webhook 接收的数据：

{
  "body": {
    "name": "John Doe",
    "email": "[email protected]",
    "message": "Hello!"
  }
}

Slack 节点的文本字段中：

New form submission!

Name: {{$json.body.name}}
Email: {{$json.body.email}}
Message: {{$json.body.message}}

示例 2：HTTP Request 到 Email

HTTP Request 返回的数据：

{
  "data": {
    "items": [
      {"name": "Product 1", "price": 29.99}
    ]
  }
}

Email 节点中（引用 HTTP Request）：

Product: {{$node["HTTP Request"].json.data.items[0].name}}
Price: ${{$node["HTTP Request"].json.data.items[0].price}}

示例 3：格式化时间戳

// Current date
{{$now.toFormat('yyyy-MM-dd')}}
// Result: 2025-10-20

// Time
{{$now.toFormat('HH:mm:ss')}}
// Result: 14:30:45

// Full datetime
{{$now.toFormat('yyyy-MM-dd HH:mm')}}
// Result: 2025-10-20 14:30

---

数据类型处理

数组

// First item
{{$json.users[0].email}}

// Array length
{{$json.users.length}}

// Last item
{{$json.users[$json.users.length - 1].name}}

对象

// Dot notation (no spaces)
{{$json.user.email}}

// Bracket notation (with spaces or dynamic)
{{$json['user data'].email}}

字符串

// Concatenation (automatic)
Hello {{$json.name}}!

// String methods
{{$json.email.toLowerCase()}}
{{$json.name.toUpperCase()}}

数字

// Direct use
{{$json.price}}

// Math operations
{{$json.price * 1.1}}  // Add 10%
{{$json.quantity + 5}}

---

高级模式

条件内容

// Ternary operator
{{$json.status === 'active' ? 'Active User' : 'Inactive User'}}

// Default values
{{$json.email || '[email protected]'}}

日期操作

// Add days
{{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}}

// Subtract hours
{{$now.minus({hours: 24}).toISO()}}

// Set specific date
{{DateTime.fromISO('2025-12-25').toFormat('MMMM dd, yyyy')}}

字符串操作

// Substring
{{$json.email.substring(0, 5)}}

// Replace
{{$json.message.replace('old', 'new')}}

// Split and join
{{$json.tags.split(',').join(', ')}}

---

调试表达式

在表达式编辑器中测试

1. 点击包含表达式的字段
2. 打开表达式编辑器（点击“fx”图标）
3. 查看结果的实时预览
4. 检查以红色突出显示的错误

常见错误消息

“Cannot read property 'X' of undefined” → 父对象不存在 → 检查数据路径

“X is not a function” → 尝试在非函数上调用方法 → 检查变量类型

表达式显示为纯文本 → 缺少 {{ }} → 添加大括号

---

表达式辅助方法

可用方法

字符串：

• .toLowerCase()、.toUpperCase()
• .trim()、.replace()、.substring()
• .split()、.includes()

数组：

• .length、.map()、.filter()
• .find()、.join()、.slice()

日期时间（Luxon）：

• .toFormat()、.toISO()、.toLocal()
• .plus()、.minus()、.set()

数字：

• .toFixed()、.toString()
• 数学运算：+、-、*、/、%

---

最佳实践

✅ 建议

• 始终使用 {{ }} 表示动态内容
• 字段名称包含空格时使用方括号表示法
• 通过 .body 引用 Webhook 数据
• 使用 $node 获取其他节点的数据
• 在表达式编辑器中测试表达式

❌ 不要

• 不要在 Code 节点中使用表达式
• 节点名称包含空格时，不要忘记加引号
• 不要额外再套一层 {{ }}
• 不要假设 webhook 数据位于根级（它在 .body 下！）
• 不要在 webhook 路径或凭据中使用表达式

---

相关技能

• n8n MCP 工具专家：学习如何使用 MCP 工具验证表达式
• n8n 工作流模式：查看实际工作流示例中的表达式
• n8n 节点配置：了解何时需要使用表达式

---

总结

基本规则：

1. 用 {{ }} 包裹表达式
2. Webhook 数据位于 .body 下
3. Code 节点中不要使用 {{ }}
4. 节点名称包含空格时要加引号
5. 节点名称区分大小写

最常见的错误：

• 缺少 {{ }} → 添加花括号
• webhook 中使用 {{$json.name}} → 使用 {{$json.body.name}}
• Code 中使用 {{$json.email}} → 使用 $json.email
• 使用 {{$node.HTTP Request}} → 使用 {{$node["HTTP Request"]}}

更多详情，请参阅：

• 常见错误 - 完整的错误目录
• 示例 - 实际工作流示例

---

需要帮助？ 请参考 n8n 表达式文档，或使用 n8n-mcp 验证工具检查表达式。